故障排查台
Markdown 文档转换故障排查
针对预览空白、任务失败、ZIP、字体、表格、公式、图表、下载和导出差异的实用排查清单。
按顺序检查
先找到第一个失败阶段,再处理对应问题
把源内容、预览、请求、任务和下载分开检查,转换失败会更容易定位。
01刚打开页面时预览为空
先等待示例内容加载完成,并确认源内容文本框中有 Markdown。如果修改内容后预览才出现,请先检查工作台脚本和 API 配置是否在测试前加载完成。
02任务还没创建就请求失败
确认源内容不为空、ZIP 中已选择 Markdown 文件,且所选输出被当前接口支持。对于过大或不安全的压缩包,不要原样反复提交。
03预览和下载文件效果不同
HTML 工作台会下载与预览相同的快照和已收集样式;DOCX 和 PDF 使用各自的原生写入器,因此请在对应下载文件中重新检查字体、纸张、页边距、标题规则、表格宽度、公式和分页。
04图片、Mermaid 或公式导致失败
使用相对本地图片路径、有效 Mermaid 语法和受支持的 TeX 定界符,超长表达式尽量拆分。ZIP 中的 Mermaid 需要工作台支持的浏览器图表资源流程。
05下载不存在或已经过期
任务完成后尽快下载。如果文件已经被自动清理,请使用可复用的 Markdown 源内容重新转换,不要继续使用已过期的临时链接。
下一步