Markdown批量转PDF实战:Pandoc+XeLaTeX全流程与自动化检查
Markdown 文件积累多了以后,最头疼的往往不是写,而是"交付"。自己看无所谓,但发给客户、同事或者放到知识库里,PDF 几乎是唯一不会被格式搞乱的格式。我之前处理过一整个文件夹的 Markdown 批量转 PDF,踩了不少坑,也摸索出一套比较顺手的流程,今天把它完整拆开讲一遍。
先说结论:批量转换这件事本身不难,难的是转换完之后的检查。你转出来的 PDF 有没有乱码、图片路径是不是失效、代码块是不是挤成一团,这些才是真正花时间的地方。所以这篇文章不只讲命令,还会讲一套我自己的"转换后检查流程",照着做,基本不会翻车。
1. 转换方案选型:别一上来就装一堆软件
Markdown 转 PDF 的方案多到让人眼花缭乱,但真正能扛住"批量"这两个字的其实就那几个。我先帮你把思路理一理,省得你装了五六个工具,最后发现没有一个能批量跑。
1.1 先想清楚你的 Markdown 是什么类型
这是最容易被忽略的一步。同样是 .md 文件,内容结构完全不一样,转换方案也得跟着变:
- 纯文本型:就是标题、段落、列表、表格、代码块,没有复杂排版。这类最简单,用 Pandoc 就能搞定。
- 图片密集型:笔记里大量插图,图片路径可能是相对的、绝对的,甚至还有网络图片。这类要额外处理图片路径映射,不然 PDF 里全是裂开的图标。
- 学术/技术文档型:带 LaTeX 数学公式、复杂的表格、交叉引用。这类对 PDF 引擎要求高,常见方案会直接翻车。
- 带特殊语法型:比如用了 Mermaid 图表、PlantUML 流程图,普通的转换工具根本不认这些语法,最后 PDF 里显示的是原始代码。
我的建议是:先随便挑一个文件夹里的文件,用你最顺手的编辑器(比如 VS Code 或 Typora)预览一下,确定它属于哪种类型,再决定用下面的哪套方案。
1.2 主流转换方案横向对比
我实际用过而且觉得靠谱的方案有以下几种,各有侧重,你按需选择:
| 方案 | 核心工具 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|---|
| Pandoc + LaTeX | pandoc + xelatex | 命令行批量灵活,排版可控 | 中文字体配置麻烦,需装 TeX 环境 | 大批量、专业排版需求 |
| md-to-pdf | npm 包 | 一键安装,自动处理代码高亮 | Node 环境依赖,定制性稍弱 | 团队已有 Node 基础 |
| VS Code 插件 | Markdown PDF / Markdown Preview Enhanced | 图形界面操作,预览即所得 | 批量能力弱,需要配合脚本 | 少量文件、临时转换 |
| Typora + 脚本 | 自带导出 + AppleScript | 所见即所得 | 并非原生批量,需要模拟点击 | 需要保留 Typora 渲染效果 |
如果让我推荐,主力方案必须是 Pandoc,没有之一。为什么?因为它是唯一一个"纯命令行可批量运行、输出质量稳定、跨平台"的方案。其他的要么是图形界面工具,批量不友好;要么是编辑器内置功能,导出效果受限。
但 Pandoc 有个中国用户绕不开的坎:中文字体配置。默认模板跑出来的中文 PDF 基本是豆腐块。所以下面我把这套方案完整讲透,包括字体怎么配。
2. Pandoc 批量转换实操:从安装到第一次运行
这一节我按"从零开始"的路径走,哪怕你之前完全没接触过 Pandoc,跟着步骤来也能跑通。
2.1 安装 Pandoc 和 PDF 引擎
Pandoc 本身只是转换器,它把 Markdown 转成 PDF 时,实际上要调一个 PDF 引擎来做最后的渲染。这个引擎就是 LaTeX 家族(推荐 xelatex)或者 wkhtmltopdf(基于 WebKit)。
我强烈建议走 Pandoc + XeLaTeX 路线,因为 XeLaTeX 对 Unicode(中文)的支持是天生的,不需要大量预配置。
安装分系统说:
- Windows:去 Pandoc 官网下载 installer,装完记得把安装目录加到 PATH 环境变量。然后装 MiKTeX 或 TeX Live(推荐 TeX Live,虽然安装包大,但库全,省了很多后来缺包的麻烦)。
- macOS:
brew install pandoc,然后是brew install --cask mactex或brew install basictex(basictex 小很多,但可能需要额外装某些宏包)。 - Linux(Ubuntu/Debian 系):
sudo apt install pandoc texlive-xetex texlive-lang-chinese,注意那个texlive-lang-chinese包,没它中文大概率出问题。
提示:安装 TeX 全家桶动辄几个 G,如果你只是偶尔转一下,也可以装精简版(basictex/MiKTeX 的自动包管理模式),让系统缺什么包时自动下载。但批量转换时不建议这样,因为中途缺包会中断整个流程,最好一步到位。
装完之后验证一下:
两个命令都能输出版本号,说明环境就绪。
2.2 搞定中文字体:一劳永逸的模板
Pandoc 默认的 LaTeX 模板里面没有适配中文字体,你直接转肯定会出现"乱码"或者"字全是方块"。解决办法是用一个自定义的 YAML 头,给 XeLaTeX 指定可用字体。
我习惯的做法是写一个 template.yaml 文件,放在固定目录下,所有项目共用:
这里有几个值得关注的点:
documentclass: ctexart是中文 LaTeX 文档类的标准选择,它内部帮你处理了大部分中文排版细节,比手动配 fontspec 省心得多。CJKmainfont指定字体。注意字体名必须是系统里已经安装的。Windows 上可以用"SimSun"、"Microsoft YaHei"(需要写成"Microsoft YaHei"带引号);macOS 上用"PingFang SC";Linux 上如果是装了文泉驿或思源黑体,就写对应字体名。toc: true是自动生成目录。批量转文档时我建议开着,方便拿到 PDF 后快速跳转检查。
字体名不确定的话,可以在命令行查:fc-list :lang=zh(Linux/macOS),Windows 上可以在字体文件夹里看到字体显示名,或者用 PowerShell 查 Get-ChildItem C:\Windows\Fonts。
2.3 批量转换命令:小心目录结构和路径
假设你的 Markdown 文件都在 /docs/notes/ 目录下,文件名可能有中文、有空格。批量转换时最容易出问题的就是文件名带空格,脚本里不加引号就被拆成多个参数了。
最稳妥的批量脚本(Linux/macOS 写法):
Windows PowerShell 写法:
这段脚本里有几个细节值得留意:
-H参数是往 PDF 头部插入内容,我这里把整个 YAML 配置塞进去了,相当于全局模板生效。--highlight-style=tango是给代码块配一个颜色方案。如果你不指定,Pandoc 默认代码高亮是黑白的,在 PDF 里看代码会很难受,尤其是缩进的 Python 或嵌套的 JSON。- 文件名里的空格、中文在双引号包裹下都能正确处理。
跑完一看,PDF 是出来了,但你会发现一个新问题:图片全裂了。这就是我开头说的,Markdown 里嵌入图片的方式千奇百怪,Pandoc 默认可搞不定。
3. 图片路径映射:批量转换最大的坑
3.1 三种常见图片路径的处理策略
Markdown 里的图片路径,基本逃不出这三种:
- 相对路径:
或 - 绝对路径:
或 - 网络图片:

逐个说:
- 网络图片:Pandoc 默认会尝试下载,但如果你在离线环境,它会报错或者留空。最省事的方法是预先用脚本把所有网络图片下载到本地,再把 markdown 里的 src 替换成本地路径。
- 绝对路径:对本机转换没毛病,但换个机器就完蛋,而且 PyPDF 合并或者上传到知识库时路径会乱。我建议统一改成相对路径,以你的"项目根目录"为基准去写。
- 相对路径:这是最理想的,但有个隐患——如果你的 Markdown 分布在多个子文件夹,而图片集中在顶层
images/,你从子目录的文件里去写../images/foo.png,Pandoc 的工作目录是当前 md 文件所在的目录,它按相对路径能找到,PDF 输出后图片就能正常嵌入。
关键点在 Pandoc 的工作目录行为。比如你在 /docs/notes/sub/ 文件夹里执行 pandoc sub/note.md,Pandoc 会以当前执行命令的位置为基准去解析相对路径,这就会出问题。所以执行命令的目录最好和你 Markdown 文件所在目录一致,或者直接用 --resource-path 参数指定图片根目录。
3.2 一个 Python 预处理脚本的示例
我实际使用的思路是这样:在批量转换前,先跑一个预处理脚本,把相对路径全部改写为"以当前脚本所在项目根目录为基准"的绝对路径,转换完成后再改回去(其实改不改回去无所谓,只要源文件是干净的就行)。
这段代码有两个关键设计:
- 统一图片目录:不管原来图片散落在哪里,全部复制到一个
images/目录下,后续不管你怎么移动 PDF 都不会出现路径问题。代价是如果两份 md 引用同名图片,会互相覆盖,复制前要做个重名检查(我这里偷懒没写,你如果文件多,建议加一个if os.path.exists判断加后缀)。 - 只处理本地图片:网络图片跳过,因为网络地址不受目录结构影响,转 PDF 时也能正常嵌入(前提是网络通)。
这个脚本跑完之后,再用 Pandoc 批量转换,你会发现图片裂掉的问题基本根治。
4. 转换后检查:批量操作的重中之重
批量转换最怕什么?不是转得慢,而是转完了你不知道哪些是坏的。100 个文件转完了,结果有 30 个图片裂了、10 个字体有问题、5 个目录是空的,你不可能一个个打开 PDF 用肉眼看。所以检查环节必须"自动化优先、人工抽查兜底"。
4.1 用 PyPDF2 或 pdfplumber 做自动化健康检查
我自己写过一个检查脚本,思路很朴实:用 pdfplumber 打开每个 PDF,统计页数、提取文本长度,和原始的 Markdown 字数做比对。如果字数差距过大,说明转换过程中某些内容被吞了。
这个脚本不是万能的,因为 Markdown 里有代码块、图片、公式,这些原始文本不会全部映射到 PDF 文本里。所以判断阈值我放宽到了 0.3——只要 PDF 提取出的文本量不低于 Markdown 原文的 30%,就认为基本正常。实际使用中,如果一个 md 文件 90% 都是图片和代码,那么这个比例会自然偏低,需要人工确认。
4.2 人工抽查清单:别省这一步
自动化只能查"有没有内容",查不了"内容排版对不对"。我总结了一个人工抽查清单,批量转换后花 10 分钟抽查 3-5 个代表性文件就够:
- 封面和目录页:目录是否自动生成?页码有没有对不上?
- 代码块是否换行:长代码是不是被截断在页面边缘?这个 Pandoc 默认会处理,但如果代码里有超长 URL 或 base64 串,还是会溢出。
- 表格宽度:宽表格是不是被强行压缩到页面里?单元格文字是否重叠?
- 数学公式:行内公式、块级公式是否正常渲染?检查一下和 LaTeX 源码的对应关系。
- 图片清晰度:嵌入的图片会不会变得模糊?如果源图分辨率太低,PDF 里放大看会糊。
针对代码溢出的问题,我习惯在 YAML 模板里加一行 lstlisting 的设置,强制代码块自动换行:
这样遇到长行就会自动断行,不会超出页面边界。
4.3 结果检查后端的修复技巧
抽查发现问题之后,修复分两类:
- 单个文件问题:直接改源 Markdown(比如把宽度过大的表格拆成两段、把源码里的长 URL 用
<br>换行),重转这一个文件即可:BASHpandoc problem.md -o problem.pdf --pdf-engine=xelatex -H ~/.pandoc/template.yaml - 整个文件夹的共性问题:比如所有 PDF 的页眉页脚没设置好、所有字体都有问题。这种情况建议改模板文件,然后全量重转。不要尝试在单文件上打补丁,因为下一次还会犯,模板一劳永逸。
5. 进阶玩法:把这些命令做成一键脚本
如果你是不定期、批量转换的"高频用户",我强烈建议把整个流程(图片预处理、批量转换、结果检查)整合成一个 shell 脚本。我自己的做法是放在项目根目录,起名 convert_all.sh,里面包含三段逻辑,整个跑下来大概需要几分钟到十几分钟(看文件数量和 PDF 引擎加载时间)。
脚本的结构我贴个核心,你可以根据自己需求改:
有了这个脚本,日常新增了几个 Markdown,只要把它拖到终端里跑一遍,等它输出一堆 [OK] 和检查结果,任务就算闭环了。我自己的体验是:这个脚本省下来的时间,比一开始标准化的时间多得多,尤其是当你一个月要整理几百个 Markdown 文件时。
6. 实测过程中的高频坑位
最后把我踩过的坑集中列一下,有些坑藏得很深,网上资料也不多:
6.1 Pandoc 转 PDF 时图片成了"空框"
这个的根因一般是图片路径含中文或空格,LaTeX 的宏包对这类路径支持不好。解决办法很简单:预处理脚本里用 shutil.copy2 复制时,统一改成纯英文文件名(比如 image_001.png),同时替换 md 里的引用路径。
6.2 表格里的长文本把页面撑爆
Pandoc 对长表格的处理策略是"能塞就塞",一旦宽度超出页面,它不会自动缩小字号,而是直接把内容推出去。解决思路是给表格加全局设置,用 longtable 或者设置自动宽度:
tabcolsep 是列间距,arraystretch 是行高。这两个调一调,表格在页面里会透气很多。
6.3 批量转换跑到一半进程被杀
这种情况几乎都是因为某个文件内有特殊字符或者路径异常,Pandoc 卡住或直接抛错。有一个实用的技巧是给 Pandoc 命令加超时机制,跑满 60 秒就自动跳到下一个文件:
如果某个文件确实转不了,至少不会卡死整批。
6.4 PDF 文件名不能用 Markdown 里的特殊字符
如果 Markdown 文件名带 #、&、% 这类字符,Windows 文件系统会拒绝创建同名 PDF。批处理脚本里最好做一个安全替换:
这个坑我是在一次批量处理读书笔记时踩到的,当时文件名类似"《K8s权威指南》#5 笔记.md",Windows 直接报错,改了半小时才发现问题。
7. 一条被低估的辅助路径:先用 HTML 再转 PDF
Pandoc 直接转 PDF 是主力方案,但我得说一句实话——在某些场景下,先转 HTML 再打印成 PDF,质量更高。尤其是你的 Markdown 用了很多自定义 CSS 样式(比如不同颜色块、自定义列表样式、多列布局),LaTeX 引擎很难还原这些效果。
具体操作是两步走:
这一步适合那些"极度依赖视觉样式"的文档。比如我的产品需求文档(PRD)就喜欢用颜色来区分"正常流程"和"异常流程",这种花哨的排版,LaTeX 很难做到,但 HTML+Chrome 打印还原度 100%。
代价是:批量控制力弱一些,因为 Chrome 无头模式一次只能处理一个文件,不像 Pandoc 那样脚本里循环跑起来很轻松。折中方案是写个循环:
实际效果实测下来,代码高亮、图片、表格、CSS 的阴影和圆角、渐变背景,全部能原样输出。如果你对排版有强迫症,这条路径值得尝试。
我自己现在的工作流里,这两套方案是并存的:笔记和文档类的批量用 Pandoc,产品和设计文档类的用 HTML+Chrome。没有哪种方案是银弹,关键是搞清楚你要转的这批文件,它们对格式还原度的要求有多高。 先把一个文件夹里的文件类型摸透,再选方案,比装十个工具瞎试要快得多。