返回博客
一般文章

修复 Markdown PDF Mermaid 导出错误

Markdown PDF 导出 Mermaid 图表失败时,可先检查脚本网址与版本,并逐种图表确认 PDF。

用 VS Code 写完 Markdown,下一步若要交付 PDF,Markdown PDF 是常见的扩展。文本和代码通常能顺利导出;文档里若放了 Mermaid 图,结果却可能只剩源代码或空白页。这篇记录当时遇到的状况,以及可以先试的设置。

Markdown PDF

扩展程序页面如下:

Markdown PDF 优点在于:

  • 直接调用 VS Code 的 Command Palette → “Markdown PDF: Export (pdf)” 即可产生 PDF,支持 HTML / PNG / JPEG 等多种输出格式。
  • 内置 puppeteer,能够在无头 Chrome 中渲染 HTML → PDF,因此数学式(KaTeX)、代码区块高亮与 CSS 布景都能完好保存。
  • 允许自订 Mermaid Server URL,这也是下面修复导出错误的关键。

安装后会在 settings.json 多出若干属性,本篇聚焦 markdown-pdf.mermaidServer。

Mermaid 导出错误

当 Markdown 内含以下语法:

text
graph TD
    A --> B
    A --> C
    B --> D
    C --> D

这段代码在网页中会显示成下图:

ABCD
上方 Mermaid 程式碼對應的流程圖。

VS Code 预览面板可能显示正常,导出 PDF 时却出现两种情况:

  1. 完全没反应:原本的 Mermaid 区块在 PDF 中被解析为纯文本,没有图表渲染。

    text
    graph TD
        A --> B
        A --> C
        B --> D
        C --> D
    
  2. 炸弹图标+空白页:PDF  内只看得到 “💣” 或整页空白,Mermaid 文本原样出现。

相关 issue 指向 Markdown PDF 与较新 Mermaid 版本之间的兼容性问题。

从 issue 的回报看,换用特定 Mermaid 版本的网址后,有些图表能恢复导出;不同版本与图表类型的结果却不一致。这表示问题和导出时加载的 Mermaid 脚本有关,不能只凭预览正常就判定 PDF 一定能用。

解决方案

可以先到设置页面找到 markdown-pdf.mermaidServer,指定 Mermaid 10.3.1,如下图:

把原本默认的网址:

text
https://unpkg.com/mermaid/dist/mermaid.min.js

取代成:

text
https://unpkg.com/[email protected]/dist/mermaid.js

其他版本可行吗?

GitHub 上也有相关的回报:

以下两则是蛮多人推荐的解决方案:

当时测试的版本中,10.3.1 能正常导出 Graph、sequenceDiagram 和 gantt。classDiagram、stateDiagram 等格式没有在这次测试范围内;升降版前,最好先用手上的图表各导出一次确认。

这个设置适合排查相同的导出症状。若扩展或 Mermaid 版本已更新,仍应以实际产出的 PDF 为准。