Pandoc 文档转换实战：从 Markdown 到 Word/PDF 的五个层级

1. 为什么我劝你别再手动排版文档了

如果你平时写技术笔记、整理会议纪要、维护项目文档，或者需要把一份内容同时输出成网页、PDF、Word 三种格式，那你大概率经历过这种崩溃：在 Word 里调了半小时的行距和标题样式，复制到网页编辑器里全乱了；用 Markdown 写完的文档，发给同事却要求必须是 Word 格式；论文投稿要求 PDF，但导师批注又得用 Word 回传。这些场景背后其实是同一个问题——内容与格式被绑死了。

Pandoc 就是专门解决这个问题的工具。它是一个开源的文档格式转换器，支持 Markdown、HTML、LaTeX、Word（docx）、PDF、EPUB、reStructuredText、AsciiDoc 等几十种格式之间的互转。你可以把它理解成文档世界的“万能翻译官”：你只管用最舒服的方式写内容，输出格式交给它来搞定。

这篇文章适合谁看？如果你是刚接触命令行、想找一个靠谱的文档转换方案的新手，前两个层级能让你快速上手；如果你已经在用 Pandoc 但每次转换都要翻文档查参数，中间层级会帮你把常用场景固化下来；如果你需要批量处理、自定义模板、甚至把 Pandoc 嵌入自动化流程，后两个层级是我踩过不少坑之后总结的进阶路径。整篇内容按五个层级递进展开，你可以按需跳读，但我建议至少把前两层看完，因为后面的所有技巧都建立在那之上。

2. 第一层级：搞懂 Pandoc 到底在做什么

2.1 它不是“格式刷”，而是“中间语言”翻译器

很多人第一次用 Pandoc 会有一个误解，以为它是像格式刷一样直接把 A 格式“刷”成 B 格式。实际上 Pandoc 的工作方式是：先把源文档解析成一种内部的抽象语法树（AST），然后再把这棵树渲染成目标格式。这个设计带来的直接好处是，任意两种它支持的格式之间都可以互转，不需要为每一对格式单独写转换器。

打个比方，这就像翻译：如果要把中文翻成法文，直接翻可能很别扭；但如果先把中文转成一种“意义表示”，再从意义表示转成法文，中间少了很多歧义。Pandoc 的 AST 就是这个“意义表示”。理解这一点很重要，因为它解释了为什么有些格式转换会丢失信息——不是 Pandoc 不行，而是目标格式本身不支持源格式的某些特性。比如你把一个带复杂表格的 Markdown 转成纯文本，表格结构必然丢失，因为纯文本没有表格的概念。

2.2 安装这件事，别想得太复杂

Pandoc 的安装是我见过最省心的之一。它本质上就是一个二进制可执行文件，没有复杂的依赖链。各平台的常见做法：

• Windows：直接去官网下载.msi安装包，双击下一步即可。装完之后打开 PowerShell 或 CMD，输入pandoc --version能看到版本号就说明成功了。
• macOS：如果你装了 Homebrew，一行命令brew install pandoc搞定。没装 Homebrew 的话下载.pkg安装包也一样。
• Linux：大多数发行版的包管理器里都有，比如apt install pandoc或dnf install pandoc。但要注意，发行版仓库里的版本可能偏旧，如果你需要最新特性，建议从官方 release 页面下载二进制包手动放置。

注意：如果你后续要输出 PDF，Pandoc 本身不直接生成 PDF，它需要调用一个 LaTeX 引擎（如 TeX Live 或 MiKTeX）或者其他的 PDF 渲染方案。这是新手最容易卡住的地方，我在第三层级会专门讲怎么处理。

安装完成后，建议先跑一个最小验证：新建一个test.md，写一行# Hello Pandoc，然后执行pandoc test.md -o test.html，打开生成的 HTML 看看标题有没有正确渲染。这一步能帮你排除 90% 的环境问题。

2.3 最核心的三个参数，记住就够用了

Pandoc 的命令行参数非常多，但日常使用中真正高频的其实就三个：

大多数时候 Pandoc 能根据文件扩展名自动推断格式，所以-f和-t可以省略。但有两种情况必须手动指定：一是输入文件扩展名不标准（比如.txt里其实是 Markdown），二是你想用某个格式的特定变体（比如markdown+pipe_tables启用管道表格语法）。我个人的习惯是，只要不是标准扩展名，一律显式写上-f，省得后面排查半天。

3. 第二层级：把常用转换场景跑通

3.1 Markdown 转 Word：职场最刚需的场景

这个场景我敢说占了日常使用的七成以上。命令本身很简单：

pandoc notes.md -o notes.docx

但直接转出来的 Word 往往不尽如人意——标题样式是 Pandoc 默认的，字体、行距、页边距都不是你想要的。这时候需要用到--reference-doc参数。它的逻辑是：你先用 Word 手动做一个“样式模板”文档，把标题 1、标题 2、正文、引用等样式调成你要的样子，然后把这个文档作为参考传给 Pandoc。

pandoc notes.md --reference-doc=my-template.docx -o notes.docx

Pandoc 会读取这个模板里的样式定义，应用到生成的文档上。这个技巧的价值在于，你只需要调一次模板，之后所有转换出来的 Word 都是统一风格。我见过不少团队把模板文档放在项目仓库里，所有人共用，出来的文档格式完全一致，省掉了大量互相“对齐格式”的时间。

实操心得：制作参考模板时，不要只改标题样式，正文的字体、段落间距、甚至页眉页脚都要设置好。另外，模板文档里不要留任何正文内容，只保留样式定义，否则那些内容可能会被带进输出结果。

3.2 Markdown 转 PDF：绕开 LaTeX 的坑

PDF 转换是新手最容易受挫的地方。Pandoc 默认走 LaTeX 路线，这意味着你机器上得有一个可用的 LaTeX 环境。完整安装 TeX Live 动辄几个 GB，对只想转个文档的人来说太重了。

我的建议是分情况处理。如果你只是偶尔转一下、对排版要求不高，可以用--pdf-engine指定更轻量的引擎。比如用wkhtmltopdf走 HTML 渲染路线：

pandoc notes.md -o notes.pdf --pdf-engine=wkhtmltopdf

这个方案的好处是不需要 LaTeX，坏处是对复杂数学公式和精细排版支持有限。如果你经常处理学术文档、需要公式和交叉引用，那还是老老实实装一个精简版的 LaTeX 发行版，比如 TeX Live 的basic方案，只装必要的包。

另一个常见需求是控制 PDF 的页面设置，比如纸张大小、边距、字体大小。这些通过-V参数传给 LaTeX 模板：

pandoc notes.md -o notes.pdf -V geometry:margin=2.5cm -V fontsize=12pt

geometry是 LaTeX 的页面布局包，margin控制边距，fontsize控制字号。这些参数在 Pandoc 的文档里没有全部列出，需要你对 LaTeX 有一点了解。我当初就是被这个卡了很久，后来才明白-V传的其实是模板变量，具体支持哪些取决于你用的模板。

3.3 批量转换：一条命令处理整个文件夹

单个文件转换用上面的命令就够了，但如果你有一个文件夹的 Markdown 要全部转成 HTML，一个个敲命令太蠢了。Linux 和 macOS 下可以用 shell 循环：

for f in *.md; do pandoc "$f" -o "${f%.md}.html" done

Windows PowerShell 下写法不同：

Get-ChildItem -Filter *.md | ForEach-Object { pandoc $_.Name -o ($_.BaseName + ".html") }

这里有个细节值得说：${f%.md}是 shell 的参数扩展语法，意思是“去掉变量 f 末尾的 .md”。这个技巧在处理批量文件时非常实用，比用sed或basename简洁得多。我第一次看到这个写法的时候还专门查了半天，后来发现它是 POSIX 标准的一部分，各种 shell 都支持。

4. 第三层级：用模板和元数据控制输出

4.1 元数据块：让文档自己说明自己

Pandoc 支持在 Markdown 文件开头写一段 YAML 格式的元数据块，用三个短横线包裹：

--- title: 项目周报 author: 张三 date: 2024-06-01 ---

这些元数据在转换时会被自动填入模板的对应位置。比如转 HTML 时，title会成为<title>标签的内容；转 PDF 时，author和date会出现在标题页上。这个机制的价值在于，文档的元信息跟着内容走，而不是散落在命令行参数里。你换一种输出格式，元数据依然有效。

元数据块里还可以放自定义字段，配合自定义模板使用。比如你定义一个company字段，然后在模板里引用它，就能实现公司名称的自动填充。这个用法在需要批量生成带统一抬头的文档时特别有用。

4.2 自定义模板：从“能用”到“好用”的分水岭

Pandoc 的模板系统基于一种简单的变量替换语法。你可以用--template指定自定义模板，模板里用$variable$的形式引用变量。获取默认模板的方法是：

pandoc -D html > my-template.html

这会输出 Pandoc 内置的 HTML 模板，你可以在此基础上修改。模板里常见的变量包括$title$、$body$、$toc$（目录）、$date$等。$body$是特殊变量，代表转换后的正文内容，必须保留。

我拿一个实际场景举例。假设你要把一批 Markdown 转成带统一页头和样式的 HTML 页面，默认模板太朴素了。你可以复制默认模板，在<head>里加上自己的 CSS 链接，在<body>开头加上导航栏的 HTML 片段，然后保存为my-template.html。之后转换时加上--template=my-template.html，所有输出就都带上了你的自定义样式。

注意：模板里的变量名是大小写敏感的，$title$和$Title$不是一回事。另外，如果某个变量在元数据里没有定义，模板里对应的位置会留空，不会报错。这个特性有时候会导致“为什么我的标题没显示”这类困惑，排查时先检查元数据块里有没有写对字段名。

4.3 目录与编号：长文档的必备配置

处理长文档时，目录和章节编号是两个高频需求。Pandoc 用--toc生成目录，用--number-sections给章节自动编号：

pandoc thesis.md -o thesis.pdf --toc --number-sections --toc-depth=3

--toc-depth控制目录包含到几级标题，默认是 3。这个参数在写论文或技术手册时很有用，因为你不希望四级、五级标题也塞进目录里，那样目录会长得没法看。

这里有个坑我踩过：--number-sections在输出 HTML 时，编号是写在标题文本里的；但在输出 PDF 时，编号是由 LaTeX 模板控制的。这意味着如果你自定义了 LaTeX 模板，可能需要额外配置才能让编号正常显示。我的建议是，如果编号对你很重要，先在默认模板下测试通过，再逐步替换成自定义模板，这样出问题时容易定位是哪一层的问题。

5. 第四层级：过滤器与自动化扩展

5.1 过滤器是什么，为什么需要它

Pandoc 的 AST 机制带来了一个强大的扩展能力：过滤器（filter）。过滤器本质上是一个程序，它接收 Pandoc 解析出的 AST，对树进行修改，然后把修改后的树交还给 Pandoc 继续渲染。这相当于在“解析”和“渲染”之间插入了一个自定义处理环节。

举个实际例子。Markdown 本身没有“给外部链接自动加图标”的语法，但你可以写一个过滤器，遍历 AST 里所有的链接节点，如果链接指向外部域名，就自动在链接文本后面插入一个图标。这样你写文档时只需要写普通链接，图标的事情交给过滤器自动完成。

Pandoc 官方推荐用 Lua 写过滤器，因为 Pandoc 内置了 Lua 解释器，不需要额外安装运行时。一个最简单的 Lua 过滤器长这样：

function Link(el) el.content:insert(pandoc.Str(" [外链]")) return el end

把这个文件保存为add-icon.lua，转换时加上--lua-filter=add-icon.lua即可生效。这个例子的逻辑是：每遇到一个链接元素，就在它的内容末尾追加一个字符串。虽然简单，但展示了过滤器的核心工作方式——拿到元素、修改元素、返回元素。

5.2 用过滤器解决实际问题：自动编号图表

技术文档里经常需要给图片和表格编号，比如“图 1”“表 2”。手动编号的麻烦在于，一旦中间插入或删除一个图，后面所有编号都要改。用过滤器可以自动处理。

思路是这样的：遍历 AST，维护一个计数器，每遇到一个图片或表格元素，就给它的标题前面加上编号。Lua 过滤器里可以用全局变量保存计数器状态：

local fig_count = 0 function Image(el) fig_count = fig_count + 1 local prefix = "图 " .. fig_count .. "：" table.insert(el.caption, 1, pandoc.Str(prefix)) return el end

这段代码的逻辑是：每次遇到 Image 元素，计数器加一，然后在 caption 的开头插入编号文本。实际使用时还需要考虑图片是否有 caption、caption 的结构是块级还是行内等问题，但核心思路就是这样。我当初写这个过滤器的时候，光是搞清楚el.caption的数据结构就花了不少时间，建议你直接用pandoc -t native把一段带图片的 Markdown 转成原生 AST 格式看看，结构一目了然。

5.3 把 Pandoc 嵌入自动化流程

当你需要定期生成文档时，手动敲命令就不合适了。常见的做法是写一个 shell 脚本或 Makefile，把转换逻辑固化下来。比如一个生成周报的脚本：

#!/bin/bash DATE=$(date +%Y-%m-%d) pandoc weekly.md \ --reference-doc=template.docx \ --lua-filter=auto-number.lua \ -o "weekly-$DATE.docx" echo "生成完毕：weekly-$DATE.docx"

这个脚本做了三件事：获取当前日期、调用 Pandoc 转换、输出结果文件名。把它加到定时任务里，每周五自动跑一次，你就再也不用记得手动生成了。

更进一步，你可以把 Pandoc 集成到 CI/CD 流程里。比如每次向文档仓库推送时，自动把所有 Markdown 转成 HTML 并部署到静态站点。这个方案在维护开源项目文档或团队知识库时非常实用，内容一更新，站点自动刷新，省掉了手动构建的环节。

6. 第五层级：性能调优与疑难排查

6.1 大文件转换慢怎么办

Pandoc 处理普通文档的速度很快，但当你转换几百页的文档或者批量处理上千个文件时，可能会感觉到明显的延迟。我实测下来，影响速度的主要因素有三个：

第一是 PDF 渲染引擎。LaTeX 引擎启动本身就有开销，如果每个文件都单独调用一次，累积起来很可观。解决方案是尽量合并转换，或者改用更轻量的 HTML 转 PDF 方案。

第二是过滤器。Lua 过滤器虽然方便，但如果逻辑复杂、遍历次数多，会成为瓶颈。我的经验是，能在过滤器里用一次遍历解决的问题，不要写成多次遍历。另外，如果过滤器里有正则匹配，尽量预编译正则表达式，而不是每次调用都重新编译。

第三是图片处理。如果文档里有大量高分辨率图片，Pandoc 在生成 PDF 时需要把图片嵌入，这个过程比较耗时。一个实用的技巧是，在源文档里引用图片时使用相对路径，并且提前把图片压缩到合适的分辨率。我一般会把文档用图控制在 150 DPI 左右，打印出来足够清晰，文件体积也不会太大。

6.2 常见报错与排查思路

下面这张表是我这些年遇到过的典型问题，按出现频率排序：

中文乱码这个问题值得单独说。Pandoc 默认的 LaTeX 模板使用的是西文字体，直接转中文 PDF 会出现方框或乱码。解决方法是指定一个支持中文的字体：

pandoc doc.md -o doc.pdf -V mainfont="Noto Sans CJK SC"

前提是你系统里装了这个字体。不同系统上可用的中文字体名称不一样，Linux 上常见的是Noto Sans CJK SC或WenQuanYi Micro Hei，macOS 上可以用PingFang SC。如果你不确定系统里有哪些字体，可以用fc-list :lang=zh命令列出所有支持中文的字体。

6.3 版本升级的注意事项

Pandoc 的版本迭代比较快，新版本有时会改变某些参数的行为，或者调整默认模板的结构。我的建议是：生产环境锁定版本，测试环境跟进最新版。如果你在脚本或 CI 流程里用了 Pandoc，最好在脚本里检查版本号，避免因为版本差异导致输出结果不一致。

另外，Pandoc 的模板格式在 2.x 到 3.x 之间有过一次较大调整，如果你有自定义模板，升级前务必在测试环境验证一遍。我当初就是从 2.x 升到 3.x 时发现模板里的某些变量名变了，导致输出文档的标题页直接空白，排查了好一阵才定位到是模板兼容性问题。

7. 几个让我少走弯路的实操习惯

第一个习惯是始终保留源文件。Pandoc 的转换是单向的，从 Markdown 转成 Word 之后，你再想从 Word 转回 Markdown，格式和结构都会有损失。所以我的做法是，所有文档都以 Markdown 为唯一真实来源，Word、PDF、HTML 都是“产物”，随时可以从源文件重新生成。这样即使输出格式出了问题，改源文件重新转一遍就行，不用去修产物。

第二个习惯是把常用命令写成脚本或别名。我日常用得最多的三条命令，分别对应周报、技术笔记和项目文档，我把它们写成了 shell 别名，敲三个字母就能执行。省下来的时间虽然不多，但减少了每次查参数的心理负担，让我更愿意用 Pandoc 而不是手动排版。

第三个习惯是定期备份参考模板。--reference-doc用的模板文档一旦丢失，重新调样式很费时间。我会把模板文件放在版本控制里，每次调整都提交一次，这样即使改坏了也能回滚。这个做法看起来有点小题大做，但当你花了两个小时调好的样式因为一次误操作没了的时候，你会感谢自己做了备份。

如果你刚开始接触 Pandoc，我的建议是从第一层级的安装和基本转换开始，先把 Markdown 转 Word 这个场景跑通。等你觉得手动敲命令烦了，自然会想去研究模板和脚本。这个过程不用急，工具的价值在于用起来顺手，而不是把所有功能都学会。