Markdown 转 PDF 的 5 种方法对比（Pandoc、VSCode、在线工具）
横向对比 5 种常见的 Markdown 转 PDF 方法：在线工具、Pandoc、VSCode 插件、浏览器打印与 md-to-pdf CLI。安装体积、首份 PDF 用时、对代码高亮、数学公式、Mermaid 的支持都列了。
大多数人最合适的方案是浏览器版的 /markdown-to-pdf —— 5 秒钟，免安装，完整支持代码高亮、KaTeX 数学公式与 Mermaid 图表。除非你要出书或写学术论文，否则 Pandoc 是杀鸡用牛刀。其他三种方法各有合适场景，但远没有网络上吹的那么万能。
我们用一份 30 页的 Markdown 报告（含代码块、KaTeX 公式、表格、Mermaid 流程图）做了对比基准。下文给出每种方法的实际表现、存在的理由，以及它真正占优的场景。
适合：一次性转换、代码高亮、数学公式、流程图、零安装。
怎么做：打开 /markdown-to-pdf，粘贴，点 PDF。
首份 PDF 时间：约 5 秒。
优点：零安装，任何浏览器都能用。完整 Markdown 支持，包括 KaTeX 与 Mermaid。明暗主题都能导出。免费账户无水印。
缺点：单文件 1 MB 上限。一次处理一个文件 —— 批量任务请看 批量转换 Markdown 文件为 PDF。
何时使用：95% 的一次性 Markdown → PDF 转换。
适合：学术论文、自定义 LaTeX 模板、参考文献引用、一份源文件输出多种格式（PDF + DOCX + EPUB）。
怎么做：
brew install pandoc
brew install --cask basictex # 或 mactex（约 5 GB）
pandoc input.md -o output.pdf
首份 PDF 时间：第一次 30–90 分钟（装 Pandoc + LaTeX，撞模板报错，修）。之后 5 秒。
优点：久经考验，可脚本化，LaTeX 模板灵活无上限。原生支持参考文献（--bibliography）。可离线运行。书本级排版品质。
缺点：LaTeX 安装包 3–5 GB。默认输出是学术论文样式。自定义模板很难。代码高亮要单独 --highlight-style 参数，且按 Web 标准看相当过时。Mermaid 需要插件。
何时使用：你要出书、写论文（带参考文献）、或者要维护三个以上 PDF 模板并希望它们进版本控制。
适合：每天都在 VSCode 里写 Markdown 的人。
怎么做：装 yzane 的「Markdown PDF」插件，右键文件 → Markdown PDF: Export (pdf)。
首份 PDF 时间：第一次约 10 秒（插件会静默下载 Chromium，约 150 MB）。
优点：在你已经在写代码的地方一键导出。可以通过用户设置改 CSS。默认样式可用。
缺点：第一次导出慢，因为要下载 Chromium。PDF 视觉风格只能改 CSS，自由度有限。开箱不支持 KaTeX —— 需要先装一个 Markdown+Math 插件来渲染。Mermaid 块会按代码渲染，不会变成图。
何时使用：你每周要写 5 份以上 PDF 且编辑器是 VSCode。
适合：Markdown 已经在浏览器里渲染好的页面（GitHub README、GitLab Wiki、文档站）。
怎么做：⌘+P 或 Ctrl+P → 「另存为 PDF」。
首份 PDF 时间：约 3 秒。
优点：已经在那儿了，不用装。任何渲染好的 HTML 都能用。
缺点：分页会以无法预测的方式切断表格和代码块。代码高亮在 Firefox 打印时容易丢色。默认页眉页脚是 URL + 页码，通常需要手动关掉。如果源页面没渲染 KaTeX 或 Mermaid，PDF 里也不会有。
何时使用：你现在就要一份某个已经渲染好的 Markdown 页面的 PDF，且不太在意品相。
适合：构建流水线、CI/CD、自动化文档。
怎么做：
npm install -g md-to-pdf
md-to-pdf input.md
首份 PDF 时间：约 10 秒（首次会把 Puppeteer 自带的 Chromium 装上，约 120 MB）。
优点：可脚本化。每个文档可以用 YAML front-matter 改主题。watch 模式实时预览。装好之后离线可用。
缺点：依赖 Node + Chromium。主题定制只能 YAML + CSS，表达力不如 Pandoc/LaTeX。开箱不支持 Mermaid，需要 markdown-it 插件。
何时使用：你的文档站在 CI 里构建 PDF；你希望 PDF 跟源文件一起进版本控制。
注意：避开旧的 markdown-pdf 包（不带连字符）—— 自 2019 年后未维护，有已知安全公告。md-to-pdf 是后续维护版本。
| 方案 | 安装体积 | 首份 PDF | 代码高亮 | 数学公式 | Mermaid | 适合 |
|---|---|---|---|---|---|---|
/markdown-to-pdf | 0 MB | 5 秒 | 是 | 是（KaTeX） | 是 | 一次性 |
| Pandoc | 3–5 GB | 30–90 分钟 | 基础 | 是（LaTeX） | 需插件 | 书、论文 |
| VSCode 插件 | 150 MB | 10 秒 | 是 | 需扩展 | 否 | VSCode 用户 |
| 浏览器打印 | 0 MB | 3 秒 | 不稳定 | 否 | 否 | 已渲染页面 |
md-to-pdf CLI | 120 MB | 10 秒 | 是 | 需配置 | 需插件 | CI/CD |
- 大多数读者 →
/markdown-to-pdf，95% 的场景这就是答案。 - 写学术论文带文献的 → Pandoc。
- 每天都在 VSCode → VSCode 插件。
- DocOps / CI 构建 →
md-to-pdfCLI。 - 现在就要 GitHub README 的 PDF → 浏览器打印，接受粗糙。
Markdown → PDF 工具最大的诱惑是过度工程。要转一份文档就别装东西。要转 1000 份就上 CLI 自动化。中间地带很少能正当化用 Pandoc 来给非学术场景用。
哪种方法保留代码高亮最好？
基于 headless Chromium 的几种（/markdown-to-pdf、VSCode 插件、md-to-pdf CLI），它们都通过真实 Chromium 渲染，所以任何 highlight.js / Prism 主题都能完整带过去。Pandoc 的 --highlight-style 按 Web 标准看相当过时。深入看：保留代码高亮的 Markdown 转 PDF。
哪种支持批量转换？
CLI 天然支持（md-to-pdf chapter*.md）。如果用网页工具做批量，请看 批量把 Markdown 文件转 PDF。
为什么不用 markdown-pdf 而用 md-to-pdf？
markdown-pdf（不带连字符）自 2019 年后未维护，有已知安全公告。md-to-pdf 是当前维护中的方案。
有 Markdown 转 PDF 的 API 吗？
有 —— 看 我们的 Markdown to Image API，支持 PDF 输出格式，可程序化生成。
哪种处理中文 / CJK 字体最好？
/markdown-to-pdf 和 md-to-pdf 用宿主浏览器的字体栈，只要系统有 CJK 字体就能用。Pandoc 配 XeLaTeX 需要显式配 mainfont:。VSCode 插件开箱中文就能用。
规模化跑哪种最便宜？
每周 100+ 份 PDF，CI 里跑 md-to-pdf 基本免费（只是算力）。偶尔用，浏览器版零成本。Pandoc 本身免费，但维护模板的工程时间是隐性成本。
该用哪种取决于你的用量。一份 PDF → 浏览器工具。1000 份 PDF → CI 里的 CLI。带文献的书 → Pandoc。在没尝过轻量方案的痛之前，别上重武器。