故障排查 — 常见错误当输出效果异常渲染、导出、布局、连线或 CLI 命令执行失败时请阅读本文档。大多数问题可通过一行命令修复。错误修复方法缺少id0和id1根单元格始终在root顶部同时包含两者形状未连接连线上的source和target必须匹配现有形状的id值自闭合的连线mxCellmxCell ... edge1 /使用带mxGeometry relative1 asgeometry /子元素的展开形式——自闭合连线无法渲染XML 注释中出现--违反 XML 规范——使用单个连字符或重新表述value中的特殊字符使用 XML 实体amp;lt;gt;quot;标签文本中的字面\n在value属性中使用#xa;进行换行形状重叠根据复杂度调整间距200–350px留出布线通道连线穿越形状添加路径点、分散入口/出口点或增加间距箭头与拐角重叠到达目标前的最终连线段长度必须 ≥ 20px——增加间距或添加路径点迭代循环永不结束5 轮后建议用户在 draw.io 桌面版中打开.drawio进行微调macOS 上找不到导出命令尝试完整路径/Applications/draw.io.app/Contents/MacOS/draw.ioLinux无头环境下输出为空白/报错在命令前加xvfb-run -aLinux--no-sandbox放在输入文件之前被解析为文件名将--no-sandbox移至命令末尾drawio-desktop#249, #1056LinuxFailed to get appData path/Home directory not accessible调用 drawio 前执行export HOME/tmpdrawio-desktop#127Linux 服务器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 不受影响。
