故障排查 — 常见错误
当输出效果异常（渲染、导出、布局、连线）或 CLI 命令执行失败时，请阅读本文档。大多数问题可通过一行命令修复。
| 错误 | 修复方法 |
|---|---|
缺少id="0"和id="1"根单元格 | 始终在<root>顶部同时包含两者 |
| 形状未连接 | 连线上的source和target必须匹配现有形状的id值 |
自闭合的连线mxCell（<mxCell ... edge="1" />） | 使用带<mxGeometry relative="1" as="geometry" />子元素的展开形式——自闭合连线无法渲染 |
XML 注释中出现-- | 违反 XML 规范——使用单个连字符或重新表述 |
value中的特殊字符 | 使用 XML 实体：&<>" |
标签文本中的字面\n | 在value属性中使用
进行换行 |
| 形状重叠 | 根据复杂度调整间距（200–350px）；留出布线通道 |
| 连线穿越形状 | 添加路径点、分散入口/出口点，或增加间距 |
| 箭头与拐角重叠 | 到达目标前的最终连线段长度必须 ≥ 20px——增加间距或添加路径点 |
| 迭代循环永不结束 | 5 轮后，建议用户在 draw.io 桌面版中打开.drawio进行微调 |
| macOS 上找不到导出命令 | 尝试完整路径/Applications/draw.io.app/Contents/MacOS/draw.io |
| Linux：无头环境下输出为空白/报错 | 在命令前加xvfb-run -a |
Linux：--no-sandbox放在输入文件之前（被解析为文件名） | 将--no-sandbox移至命令末尾（drawio-desktop#249, #1056） |
Linux：Failed to get 'appData' path/Home directory not accessible | 调用 drawio 前执行export HOME=/tmp（drawio-desktop#127） |
Linux 服务器：segfault / EGL / MESAfailed to load driver错误 | 添加--disable-gpu（无 GPU 时禁止 Chromium GL 初始化） |
| PDF 导出失败 | 确保 Chromium 可用（draw.io 桌面版已捆绑） |
| CLI 导出中背景色错误 | 已知 CLI 缺陷；添加--transparent标志或通过样式设置背景 |
| 草稿 PNG 在视觉 API 返回 400 “Could not process image” | 在不加-e的情况下重新导出预览（issue #8）。根本原因是-ePNG 中 IEND 块被截断，而非zTXt块本身——但对于预览，跳过-e是最简单的修复方法。 |
最终-ePNG 无法在图像查看器/视觉 API 中打开 | 运行python3 <this-skill-dir>/scripts/repair_png.py <path>。draw.io CLI 生成的-ePNG 在 IEND 处存在 8 字节截断。SVG/PDF 不受影响。 |
