OmniDocMarkdown导出PDF是空白页怎么解决
Markdown导出PDF后出现空白页或正文缺失，常见原因是源文件为空、编码或字体不对、渲染未完成。本文给出判断症状、逐项排查和预防的方法。
如果你用 Markdown 写完文档，导出 PDF 后打开只看到一页白纸，或者只有页码和页眉没有正文，问题通常不在导出工具本身，而在某个环节的内容、编码、字体或渲染状态。这篇文章写给正在写技术笔记、论文草稿、读书摘要或项目文档，需要把 Markdown 转成 PDF 交付的人。
读完你应该能做三件事：先用几分钟判断空白属于哪一类，再按从易到难的顺序逐项检查，最后把修复方法固定下来，避免下次再遇到同样的问题。下面的方法适用于大多数先把 Markdown 渲染成 HTML 再输出 PDF 的流程，也适用于在线转换工具和桌面软件。
Markdown 导出 PDF 空白，怎么办？一句话结论
先确认源文件本身有可见文字，再检查编码和字体，最后看渲染是否完成。大多数空白问题在前两步就能解决，不必急着更换工具。
| 你的情况 | 推荐做法 | 原因 |
|---|---|---|
| 源文件打开就是空的，或只有开头的元数据块 | 先补全正文，保存后重新导出 | 导出器只能输出它读到的内容，源头为空，结果必然空白 |
| 中文显示为方框，或完全不见 | 另存为 UTF-8，指定含中文字形的字体 | 编码错误或缺字体时，文字要么乱码，要么不被绘制 |
| 公式、流程图或代码高亮区域空白 | 等渲染完成后再导出，导出前在预览中确认图表已显示 | 脚本没跑完就生成 PDF，这些区域会留空 |
| 在线转换网站上传后得到空白文件 | 在本地检查原文件，并用精简样例再测一次 | 上传过程可能丢失内容，或网站对特殊语法的处理有差异 |
先判断是哪一种问题
先看症状，再对号入座，可以少走很多弯路。
| 症状 | 常见原因 | 怎么确认 |
|---|---|---|
| PDF 全是空白，页数正常 | 源文件为空、正文被注释掉、样式隐藏了正文 | 用纯文本编辑器打开源文件看是否有正文；在浏览器中打开中间生成的 HTML 看内容是否可见 |
| 只有中文不显示，英文正常 | 编码不是 UTF-8，或字体缺少中文字形 | 用编辑器查看或切换编码后重新导出；在 PDF 中尝试选中文字，看是否有可选文本 |
| 只有公式、图表或代码块空白 | 渲染脚本未完成，或相关插件未加载 | 导出前在预览中查看这些区域是否已显示为图形或高亮代码 |
| 页面上方大片空白，正文挤在下一页 | 页边距、分页符或打印样式设置异常 | 翻到第 2、3 页，判断内容是否被推到了后面 |
| 某个阅读器空白，换一个正常 | 阅读器对字体或特殊对象的支持不同 | 用另一个 PDF 阅读器或浏览器打开同一文件 |
逐项排查和修复
- 检查源文件是否有内容。 用纯文本编辑器打开 .md 文件，确认正文没有被包在注释符号
<!-- -->里，也没有整段被误放进代码围栏。如果文件只有开头的元数据块而正文为空，补上正文后再导出。 - 检查编码。 在编辑器中把文件另存为 UTF-8。某些桌面办公软件或旧工具保存的文件可能是 GBK 编码，导出后中文会变成方框或直接消失。保存时注意是否带 BOM，以导出工具的说明为准。
- 确认中文字体。 如果导出环境支持指定字体，选择一个含中文字形的字体，例如系统自带的黑体或宋体，也可以使用开源中文字体。若你在样式文件里设置了字体列表，确认其中有中文字体名，并且这台电脑上已安装该字体。
- 检查隐藏样式。 如果导出链路经过 HTML 和 CSS，搜索样式中是否有
display: none、visibility: hidden，或文字颜色与背景色相同的设置。另外留意@media print中是否隐藏了正文所在的容器，宽度被设为 0 的容器也会让内容消失。 - 等待渲染完成。 含公式、流程图和代码高亮的文档，需要脚本先把它们转换成图形。若导出工具提供等待或延迟选项，适当增加等待时间。在浏览器中手动打印时，先确认页面上的图表已经显示，再执行打印。也可以先在 UniDoc 网页编辑器（app.unidoc.top）中打开内容，确认公式和图表能正常显示，再决定导出方式。
- 处理图片路径。 图片链接失效或使用了不存在的相对路径，通常只会让图片位置空白，文字仍会显示。把图片放到文档同一目录或其子目录中，统一使用相对路径，然后对比导出前后的结果。
- 分段二分排查。 把文档从中间切开，分别导出两部分。哪一部分空白，就在那部分中逐段删减，通常几轮就能定位问题。未闭合的代码围栏是常见元凶，它会把后面所有内容都当成代码吞掉。
- 换阅读器确认。 如果 PDF 文件本身没有问题，只是某个阅读器显示空白，换一个阅读器或浏览器打开。仍然空白，再回到前面几步检查。
怎样避免下次再出现
- 固定写作环境。 新建文档时就保存为 UTF-8，并在模板中预先设置好中文字体，避免每次临时调整。
- 导出前做一次预览检查。 正文、公式、图表和代码块都要在预览中显示正常，再执行导出。
- 保留一份精简样例。 样例只包含一个标题、一段中文、一个公式和一张图。每次更换工具或修改样式后，先用它验证导出链路。
- 减少复杂结构。 尽量少在 Markdown 中混写大段 HTML，也少依赖需要额外脚本才能显示的语法，这样渲染失败的概率更低。
- 图片使用相对路径。 把素材放在文档旁边的目录里，移动文件夹时不会丢图。
- 导出后搜索一个关键词。 在 PDF 中搜索文档里的某个中文词，能搜到说明文字层正常；搜不到，说明文字没有被正确写入。
- 记录导出环境。 记下工具版本、所用字体和系统信息，下次出问题时便于对比。
❓ 常见问题（FAQ）
1. 导出的 PDF 只有页码和页眉，正文空白，是什么原因？
多半是正文被注释、被隐藏样式覆盖，或者某段未闭合的语法把后面的内容全部吞掉了。先用纯文本编辑器检查源文件，再按上面的第 1、4、7 步排查。
2. 为什么中文显示成方框，英文却正常？
这通常是字体缺少中文字形，或文件编码不是 UTF-8。换成含中文的字体并确认编码后重新导出，一般就能解决。
3. 用免费工具导出时，怎样避免空白和水印问题？
挑选时可以看几件事：是否限制文件大小和页数，导出结果是否带水印，是否保留文字层和原有排版，以及对文件隐私的说明是否清楚。用一份含中文、公式和图片的精简样例先测试，比只看宣传页面更可靠。
4. 导出的 PDF 能正常显示，但复制出来的文字全是乱码，怎么办？
这说明字体嵌入或字符映射有问题。改用包含完整字体的导出设置，或在导出前把字体换成常见的中文字体，然后复制一小段文字测试。
5. 空白是导出工具的问题，还是我的 Markdown 写错了？
用精简样例对比即可判断。同一份样例导出正常，而正式文档空白，问题多半出在文档内容上；样例也空白，问题多半出在环境或工具设置上。
📝 总结
Markdown 导出 PDF 空白，大多来自源文件为空、编码或字体不对，或者渲染没有完成。先判断症状，再按从易到难的顺序排查，并用一份精简样例做对照，通常就能找到原因，之后也能避免反复出现。
