pandoc 3.1.1 Windows 使用指南：轻松实现 Markdown 批量转 Word 与 PDF

简介：Pandoc 3.1.1 是面向 Windows 64 位系统的文档格式转换工具，适用于需要在 Markdown、Word、Excel、HTML 等格式间灵活切换的技术写作者、学术研究者和项目协作人员。压缩包共包含 4 个文件，主要为可直接运行的 pandoc.exe 主程序，以及 txt、rtf、html 格式的说明与许可文档，整体体积仅 25.09MB，轻量且便于部署。通过命令行即可实现常见转换，例如将 Markdown 文件输出为 .docx 文档，或通过中间 CSV 步骤进一步导入 Excel，保留标题、列表、引用等结构；同时支持批量处理及自定义模板，能有效提升文档规范化效率。目前已有 808 人学习下载，适合希望降低跨平台格式转换成本、简化办公文档流程的用户收藏使用。 在这个批量文档处理的需求里，很多人第一眼看到的是“pandoc-3.1.1-windows-x86-64.zip”这个文件名，第一反应是“又是个压缩包”，第二反应是“解压完不知道扔哪儿”。这个工具本身，是文档格式转换领域绕不开的一个名字：同一份 Markdown 源码，我想让它变成 Word 交差、变成 PDF 存档、变成 HTML 发网页，过去得开三个不同软件来回调整格式，而现在只需要一条命令。这篇博文就围绕这个 zip 包本身和它背后的工具链展开，写给那些刚下载完、还没想清楚下一步的人。

你会看到完整的安装思路、核心命令的底层逻辑、批量转换的写法，以及我在 Windows 上实际踩过的几个坑。如果你手里正好有一份写好的 Markdown 或者 LaTeX 文件，打算把它变成 docx 或者 PDF，这篇文章可以直接照着操作。

1. 拿到 zip 包之后，先把三件事想清楚

1.1 为什么官方要发行 zip 而不是 exe 安装包

很多 Windows 用户习惯了下安装包、点下一步、直到“完成”这个流程。pandoc 的官方 GitHub Release 页面里同时提供了 msi 安装包和 zip 压缩包，两者解决的问题不一样。msi 适合单机安装，会自动写注册表、自动加环境变量，图形界面用户双击就能结束战斗。但如果你是团队内部要分发同一版本、想在多台机器上保持完全一致的转换环境，或者根本没有管理员权限去执行安装程序，zip 包就是唯一选择：解压即用，不写注册表，不污染系统，删掉整个文件夹就等于卸载干净。

这个特性在 CI/CD 流水线里尤其值钱。我见过不少团队把 pandoc 放进 git 仓库直接作为项目依赖，每次构建时调用的都是仓库里这个固定版本，彻底杜绝了“本地能跑、服务器跑不了”的版本漂移问题。

1.2 “x86-64”到底意味着什么

文件名里的 x86-64 指的就是 AMD64 指令集，覆盖了当下几乎所有 Windows 桌面和服务器平台。如果你的机器是 2020 年之后买的，不论 Intel 还是 AMD，基本都是这个架构。需要留意的是，如果你手头是遇到 ARM 版 Windows（比如 Surface Pro X 这类设备），那就得去官方 Release 页面下载 pandoc-3.1.1-arm64.zip，两者的二进制并不通用。

另外一个容易踩的小误区是：32 位 Windows 能不能跑 x86-64 版本？不能。32 位系统需要找 x86 或 win32 的包。虽然现在装 32 位 Windows 的机器已经很难遇到了，但如果是在虚拟机里维护老系统，这个细节能省你不少排查时间。

1.3 解压位置和 PATH 环境变量的关系

zip 包解压出来是一个名为 pandoc-3.1.1 的文件夹，里面有 pandoc.exe、pandoc-lua.exe 两个可执行文件，以及一堆 dll 和默认模板目录。在这个阶段，我强烈建议直接把整个文件夹移动到一个固定位置，比如 D:\Tools\pandoc，而不是放在下载目录里不管。

因为接下来要把这个目录加入系统 PATH 环境变量。PATH 是 Windows 在执行命令时自动搜索可执行文件的目录列表。只有把 pandoc.exe 所在目录加进去，你才能在任意路径下直接敲 pandoc 命令，而不是每次都得 cd 到解压目录里。路径选择上顺带提醒一句：路径里不要带中文、不要带空格，否则后续在一些脚本场景里会遇到奇怪的引号问题，这是我实测下来最省心的方案。

注意：如果解压后直接双击 pandoc.exe，窗口会一闪而过，这是正常现象。这个工具是命令行程序，需要配合终端使用。

2. 核心命令逻辑：Markdown 转 docx 与 PDF 的原理拆解

2.1 最简单的转换命令，背后发生了什么

安装配置好之后，第一个验证命令我推荐你打开终端，敲下面这行：

pandoc input.md -o output.docx

这条命令的核心逻辑是把 input.md 通过 pandoc 内置的 AST（抽象语法树）机制做一次中间转换。整个过程可以理解成：先把 Markdown 解析成一棵结构树，树的每个节点是标题、段落、列表、引用、代码块等语义元素；然后再把这棵树按 docx 的规则重新渲染。好处是转换过程中可以对结构树做各种变换，比如过滤掉某些元素、调整标题层级、替换样式，这为后面进阶玩法和自动化打下了基础。

如果想要输出 PDF，情况会稍微复杂一些。pandoc 本身不直接生成 PDF，而是通过 LaTeX 引擎或者 wkhtmltopdf、weasyprint 这类外部工具来间接完成。也就是说，你的系统里必须额外装一个引擎。以 LaTeX 路线为例：

pandoc input.md -o output.pdf --pdf-engine=xelatex

用 xelatex 的原因很现实：默认的 pdflatex 对中文支持非常糟糕，而 xelatex 配合 ctex 宏包能比较优雅地解决中文字体问题。如果你对中文字体有定制需求，可以在命令里加上 -V mainfont="Microsoft YaHei" 这类参数，直接指定使用系统里的字体。

2.2 --standalone 参数什么时候必须加

刚开始用 pandoc 的人很容易忽略一个细节：不加任何参数时，pandoc 输出的 HTML 是文档片段，不是完整的 HTML 页面。片段的意思是没有 html、head、body 这些骨架标签，适合嵌入到已有页面中。但如果你想生成一个能独立打开的文件，必须加 --standalone（可简写为 -s）。

pandoc input.md -s -o output.html

加了这个参数之后，pandoc 会用默认模板生成一份完整的 HTML 文件，自带头部信息和基本样式。同理，如果你未来从 docx 往 Markdown 反向转换，--standalone 也会影响输出内容是否包含元数据块。这个参数在你的使用过程中会反复出现，建议一次性记牢。

2.3 格式互转的边界：哪些能转，哪些别硬来

pandoc 号称支持几十种格式互转，但“支持”不等于“无损”。我做个实际对比测试帮助理解：

我的经验是：凡是“文档型”格式（Markdown、docx、HTML、LaTeX、EPUB）之间互转，效果都很能打；凡是“排版型”格式（比如 PDF 直接转 Markdown），pandoc 也能做，但本质是解析 PDF 提取文本，格式和图片位置必然有损，不要期待完美还原。

3. 批量转换：用 for 循环把 Markdown 文档库一键导出

3.1 Windows 终端里的 for 循环怎么写

实际工作中，一次只转一个文件的情况太少了。通常是一整个目录下几十个 Markdown 文档，需要全部导出为 docx 发给别人审阅。Windows 自带的终端里可以用 for 循环实现批量处理：

for %i in (*.md) do pandoc "%i" -o "%~ni.docx"

这里有两个细节值得解释一下。%i 是循环变量，每个匹配到的 .md 文件会依次被赋值给这个变量；%~ni 的含义是“去掉扩展名的文件名”，也就是把 input.md 变成 input。加上引号是为了防止文件名里出现空格或特殊字符时命令被切断。如果你要把这段代码写进 .bat 脚本文件里，循环变量需要写成双百分号，也就是 %%i，否则脚本执行时会报语法错误。

如果你更习惯用 PowerShell，写法也更符合阅读习惯：

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

3.2 批量转 PDF 时，如何绕开中文字体问题

批量转 PDF 的代码逻辑跟上面一样，但实际执行你会遇到一个很常见的坎：如果直接跑 pandoc input.md -o output.pdf，大概率会报错，提示缺少 CJK 字体支持。解决方式是在命令里显式指定引擎和字体：

for %i in (*.md) do pandoc "%i" -o "%~ni.pdf" --pdf-engine=xelatex -V mainfont="SimSun" -V CJKmainfont="SimSun"

SimSun 是宋体，Windows 系统自带的，不需要额外安装字体，适合正式文档；如果你更想让 PDF 呈现现代感，可以把字体换成 Microsoft YaHei（微软雅黑）。还有一个很实用的参数是 -V geometry:margin=2.5cm，用来控制页面边距。如果你发现导出的 PDF 页边距太宽或者太窄，优先检查这个参数，而不是去改 LaTeX 模板。

3.3 给所有输出文件统一加页眉页脚

如果你在写技术方案或者投标文档，页眉页脚是个绕不开的需求。pandoc 的 docx 输出并不能像 Word 那样直接配置页眉，我的处理方式是转换完成后，再用 PowerShell 调用 Word 的 COM 对象统一处理。这里给一个可用版本：

$word = New-Object -ComObject Word.Application $word.Visible = $false Get-ChildItem *.docx | ForEach-Object { $doc = $word.Documents.Open($_.FullName) $section = $doc.Sections.Item(1) $header = $section.Headers.Item(1) $header.Range.Text = "内部资料 请勿外传" $doc.Save() $doc.Close() } $word.Quit()

这段脚本会遍历当前目录下所有 docx 文件，逐个打开后在页眉区域写入指定文本。第一次运行时有可能因为 Word 的权限设置卡住，只要确保你的终端不是以受限制的用户身份运行基本就不会有意外。

4. 转换报错排查链路：从“Fatal Error”到正常输出的完整过程

4.1 “pdflatex not found”不是 pandoc 的问题

pandoc 报错的风格是简单粗暴的，很多新手看到满屏红色Fatal Error直接心态崩了。我有一个标准排查思路，按这个链路走能解决九成问题。

如果用pandoc input.md -o output.pdf报错，最可能的情况是系统里没有任何可供调用的 PDF 引擎。你要检查的不只是有没有安装 MiKTeX 或者 TeX Live，还要确认安装之后有没有把引擎所在目录加入 PATH。直接在终端执行xelatex --version，如果提示“不是内部或外部命令”，那说明引擎没装好或者没加进 PATH。把 MiKTeX 装完重启终端再试一次，这个问题就消失了。

4.2 路径里有空格导致找不到输入文件

Windows 的路径系统跟类 Unix 系统不一样的一点是，很多目录天然带着空格，比如 C:\Users\Your Name\Documents。如果你在命令里不带引号直接写路径，pandoc 就会把路径按空格拆成两段，自然找不到文件。

这个问题的排查并不难，但出现的频率非常高。两个铁律：第一，所有输入输出路径全部用英文双引号包裹；第二，给本人用的工具目录不要放在带空格的路径下，比如别把 pandoc 放进 C:\Program Files 里长期使用，虽然也能通过引号调用，但脚本嵌套时会很痛苦。我自己的习惯是把工具统一放在 D:\Tools 下面，路径干净，不管是 cmd 还是 PowerShell 都不会闹脾气。

4.3 模板文件缺失时的报错处理

升级 pandoc 版本后，有时会遇到默认模板找不到的报错，尤其是使用--standalone或者生成 PDF 时。原因是新版本对模板的搜索路径有要求，它默认在当前用户目录下查找 ~/.pandoc/templates。如果你曾把旧版模板放在这个位置，升级之后格式不匹配同样会报错。

最简单的解法是直接把整个模板目录临时重命名，比如改成 templates-bak，然后让 pandoc 走内置模板逻辑重新生成：

pandoc input.md -s -o output.html --print-default-template=html > %APPDATA%\pandoc\templates\default.html

如果是 PDF 模板，把上面命令里的 html 换成 latex 再执行一次即可。这个操作的原理是告诉 pandoc：别找我自定义模板，重新给我生成一份当前版本对应的默认模板。实测下来，这个办法能解决升级后的大部分模板报错。

4.4 输出目录不存在

还有一个特别隐蔽的坑：当输出路径指向一个不存在的目录时，pandoc 不会自动创建目录，而是直接报错。比如：

pandoc input.md -o D:\output\docx\result.docx

如果 D:\output\docx 不存在，pandoc 会以失败告终。解决办法是在命令前先创建目录或者脚本里加一行判断，用批处理的话就是：

if not exist "D:\output\docx" mkdir "D:\output\docx"

这个小问题在批量转换场景里尤其常见，因为批量脚本通常是针对“目录已存在”这个假设写的，但新环境上第一次跑，输出目录很可能根本没有。建议在任何自动化脚本里都加上目录预检逻辑。

5. 版本选择与升级策略：为什么 3.1.1 值得盯住这一版

5.1 主版本号的背后是功能边界

pandoc 的版本号演进其实反映了工具定位的扩张。老用户可能还记得，pandoc 1.x 时代它主要处理 Markdown 和 HTML 之间的转换，功能很聚焦；2.x 时代加入了 docx 的原生读写，这让很多人彻底告别了 LaTeX 转 Word 的繁琐流程；3.x 时代则主要在 Lua 过滤器、模板引擎和各种格式的细粒度控制上做文章。

3.1.1 这个版本在当前生态里的位置，可以理解为一个性能、稳定性和兼容性都比较平衡的点。它支持最新的 CommonMark Spec，对 Markdown 表格的扩展也压制得很好。如果你是从非常老的版本（比如 2.0 之前）直接跳到 3.x，需要有一点心理准备：部分自定义模板语法和 Lua 过滤器 API 发生了变化，升级后要在小样本上先测试一遍。

5.2 如何保留多个版本并随时切换

有些项目可能依赖旧版本的某个特定行为，直接全局升级有风险。这时候 zip 包的优势就出来了：把 pandoc-3.1.1 和 pandoc-2.19.2 分别放在不同目录，想用哪个版本就用完整路径调用哪个：

D:\Tools\pandoc-3.1.1\pandoc.exe input.md -o output.docx D:\Tools\pandoc-2.19.2\pandoc.exe input.md -o output.docx

如果你不想每次敲这么长的路径，也可以写两个 .bat 脚本，分别叫 pandoc-latest.bat 和 pandoc-legacy.bat，把调用命令封装进去，这样就实现了命令级别的版本切换。这个方法在团队协作里非常实用，可以通过脚本明示当前文档应该用哪个版本来构建。

5.3 升级后必须回归测试的四个场景

我每次升级 pandoc 之后，不会急着全面替换，而是拿几个具有代表性的样本做一轮快速回归：

• 一个包含标题、列表、代码块和引用块的中文 Markdown 文档，转 docx
• 同一份文档转 PDF（xelatex 引擎）
• 一个带复杂表格和图片的 docx，反向转 Markdown
• 一个使用 Lua 过滤器做自定义处理的脚本跑一遍

这四个场景基本能覆盖日常高频需求。如果这些测试结果和旧版本有明显行为差异，我会去翻官方 changelog 确认影响面，而不是盲目相信“新版一定更好”。这个习惯帮我避免过好几次“升级一时爽、上线火葬场”的局面。

6. 在 Windows 上把 pandoc 变成自动化工作流的一环

6.1 定时任务：每天凌晨自动把 Markdown 转成 PDF

Windows 计划任务可以替代“每天手动跑一遍命令”的重复劳动。你只要写一个批处理脚本，然后用任务计划程序每天触发即可。脚本内容如下：

@echo off cd /d D:\work\docs for %i in (*.md) do pandoc "%i" -o "D:\work\publish\%~ni.pdf" --pdf-engine=xelatex -V CJKmainfont="SimSun"

在任务计划程序里创建任务时，触发条件选“按预定计划”设为每天 00:30，操作选择“启动程序”，程序填这个 .bat 文件路径就可以了。前提是这个时间段电脑是开机状态，或者你设置了“如果错过计划开始时间则立即启动任务”。

6.2 配合剪贴板，实现“选中即转换”

如果你写文档的手感是永远离不开 Markdown 编辑器，同时领导只收 Word，那可以用一个小技巧提升效率：把 pandoc 命令绑定到一个快捷方式上。具体操作是创建一个指向命令行的快捷方式，目标填：

C:\Windows\System32\cmd.exe /c "pandoc %1 -o %~n1.docx"

不过这个方式只适合单个文件右键操作，不够顺手。更优雅的做法是使用 PowerShell 脚本从剪贴板读入 Markdown 内容，通过管道传给 pandoc，再直接把生成结果写到桌面或其他约定位置。核心逻辑是：

Get-Clipboard | pandoc -f markdown -t docx -o output.docx

实测下来，这个方法应付日常零散转换需求非常省事，复制即转，免去临时建文件的步骤。

6.3 与 Typora、VS Code 插件的联动场景

Typora 自带导出 PDF 和 Word 的能力，在某些场景下确实方便，但它的导出逻辑是封装好的，用户在样式细节上的控制很有限。如果你用 VS Code 写作，可以考虑安装一个名为 Markdown PDF 的插件，也可以自己在 tasks.json 里配置一个自定义任务去调用 pandoc。

我的个人习惯是：编辑器只负责写和看，最终格式统一交给命令行，不绑定任何一个编辑器的导出按钮。因为团队里有人用 Typora、有人用 VS Code、有人用 Obsidian，大家写出来的文件源格式都是 Markdown，交付时跑同一条构建脚本，就能保证所有人拿到的 docx 或 PDF 样式完全一致，不会有“他用 Typora 导出的样式跟我的不一样”这种扯皮。

7. 再往前一步：用 Lua 过滤器完成自动编号与格式修正

7.1 Lua 过滤器能改什么

pandoc 的 AST 机制给了用户一个很大的操作空间：你可以在渲染之前插入一个 Lua 脚本，对所有元素做遍历和修改。比如给所有二级标题前面自动加上“第X章”，或者把所有图片的宽度统一设定为页面宽度的 80%。

一个最简单的过滤器框架长这样：

function Header(el) if el.level == 2 then el.content = pandoc.Str("自动前缀 ") .. el.content end return el end

这个函数的意思是：如果遇到一个二级标题，就在它的文本内容前面加上“自动前缀”。保存成 prefix.lua 之后，在转换命令中这样调用：

pandoc input.md -o output.docx --lua-filter=prefix.lua

7.2 用 Lua 过滤代码块语言标注

Markdown 里的代码块经常带有语言标注，比如python 或javascript。默认情况下，docx 输出会保留这些语言信息，但不会转换成 Word 的代码高亮样式。如果想要把语言标注直接嵌入到输出的代码块文本中，可以用过滤器来处理。

这个思路的核心在于对整个代码块元素做钩子处理，拿到语言类型后重新构造内容。它对 Word 本身的高亮机制无能为力，但至少能让纯文本环境下看出这是什么语言的代码，避免拿到文档后一脸茫然。

7.3 不要忽略过滤器的调试手段

Lua 过滤器写多了之后，最常见的坑是脚本报错但不知道错在哪一行。pandoc 提供了一个调试参数，可以在转换时把内部 AST 结构打印出来：

pandoc input.md -t native

这个命令不会生成普通文档，而是把 AST 结构以接近 Lua 数据结构的形式输出到终端。你可以先跑一下这个命令，看看你试图拦截的元素到底长什么样、字段名是什么、层级关系如何，再回来改脚本。这比盲猜字段名高效得多。

我在刚开始写 Lua 过滤器的时候，就是靠这个命令一点点核对代码块元素里究竟存了哪些字段，后来才明白语言标识存储在什么位置、内容又是如何表示的。掌握了这个调试方法，过滤器基本就不会再瞎写了。

8. 几个我至今还在用的日常小技巧

最后分享几个零散但很实用的点，都是我在实际使用中验证过的。

如果你经常用 pandoc 转 docx 做为正式交付文件，可以考虑把默认样式表导出出来改一改，改完每次用--reference-doc=custom.docx调用。这样你对 Word 里的标题颜色、正文字体、行距都有完全控制权，不需要每次转完手工调。第一次生成参考文档的命令是：

pandoc -o custom.docx --print-default-data-file reference.docx

这个文件生成后，用 Word 打开，调整好样式再保存，后续每次转换都会自动套用。

如果你在脚本里发现 pandoc 执行耗时异常，比如转一个文件卡了十几秒，优先检查是不是文档里有大量内嵌图片，或者 LaTeX 引擎是第一次运行导致需要生成缓存。这两个原因分别对应不同的优化方向，前者是图片压缩问题，后者是编译缓存问题。

如果你用 pandoc 的频率极高，建议把几个常用命令做成 .bat 或 PowerShell 函数放到 PowerShell Profile 里，下次直接敲一个简短的函数名就能完成转换。这一步的前期投入很少，但日积月累省下的时间非常可观。无论你是因为什么机缘下载了这个 zip 包，花点时间把这一条命令链玩熟，后续所有跨格式文档转换的问题都会变得很轻松。

本文还有配套的精品资源，点击获取