Markdown 转 Word 命令行方案：Pandoc 完全指南
想在命令行把 Markdown 转成 Word，答案就是 pandoc，而且整件事只需要一行：
pandoc report.md -f gfm -o report.docx
这条命令能搞定大多数文档。那些"一行命令"式教程不会告诉你的，是它在哪里会失灵——而且网上关于 pandoc 局限的说法，有不少已经过时了。我用 Pandoc 3.7.0.2 实际跑了一遍测试：一个塞满表格、任务列表、LaTeX 公式和 Mermaid 图表的 Markdown 文件，转换后解压 .docx，逐项检查里面到底生成了什么。有几个结果出乎我的意料。
这篇指南依次讲安装、值得记住的命令、DOCX 样式定制、批量转换，以及基于那次实测的一份诚实清单：pandoc 在哪里会出问题，什么时候在线转换工具反而是更好的选择。
👉 直接看测试结果 | 跳到命令行与在线工具的对比
安装 Pandoc
Pandoc 是单个二进制文件，各主流平台都有安装包：
- macOS：
brew install pandoc - Windows：
winget install --id JohnMacFarlane.Pandoc（或使用 MSI 安装包） - Debian/Ubuntu：
sudo apt install pandoc
在相信系统自带的旧版本之前有一点要留意：发行版仓库里的 pandoc 往往落后好几年。Ubuntu LTS 长期停留在 2.x，而当前的发布线是 3.x——下文你会看到，版本新旧直接决定哪些内容能干净转换。用 pandoc --version 查一下自己的版本。
基本转换命令详解
最简命令已经能用，但在实际项目里，真正干活的是这几个参数：
pandoc report.md -f gfm -o report.docx --toc
| 参数 | 作用 | 什么时候需要 |
|---|---|---|
-f gfm | 按 GitHub Flavored Markdown 读取 | 文件里用了表格、任务列表或删除线 |
-o report.docx | 指定输出文件，格式由扩展名推断 | 始终需要 |
--toc | 根据标题自动插入目录 | 超过几页的文档 |
--reference-doc | 套用模板 DOCX 里的字体和样式 | 公司品牌规范（见下一节） |
为什么用 -f gfm 而不是 pandoc 默认的 Markdown 方言？因为今天大多数人写的 Markdown——GitHub README、ChatGPT 和 Claude 的输出、Notion 导出——都是 GFM。pandoc 的默认方言更偏学术：它启用脚注和引文，但对个别语法的解释不太一样。如果你的源文件来自 AI 助手或开发者工具，gfm 是更稳妥的读取器。
关于数学公式：在当前版本的 pandoc 里，GFM 读取器下 $...$ 和 $$...$$ 直接可用，公式会变成 Word 原生方程而不是图片。下文会展开讲，因为这是网上被以讹传讹最多的一条 pandoc 行为。
用 reference-doc 模板定制输出样式
pandoc 生成的 DOCX 在 Word 里打开是一副通用样式。如果文档必须匹配公司模板，靠参数是修不出来的——要用参考文档（reference document）。
整个工作流分三步：
-
先生成 pandoc 的默认模板作为起点：
pandoc -o custom-reference.docx --print-default-data-file reference.docx -
用 Word 打开
custom-reference.docx，编辑其中的样式——标题 1、正文、表格、代码块。这个文件里的文字内容会被忽略，只有样式和页面设置会被继承。 -
带上模板执行转换：
pandoc report.md -f gfm --reference-doc=custom-reference.docx -o report.docx
pandoc 手册记录了哪些样式名会被识别。理解这套机制的关键心智模型：你不是在给某一份文档排版，而是把公司的 Word 样式教给 pandoc 一次，之后每次转换都能复用。
批量转换多个文件
这是命令行真正碾压任何网页工具的地方。转换整个文件夹：
Bash（macOS/Linux）：
for f in docs/*.md; do
pandoc "$f" -f gfm -o "${f%.md}.docx"
done
PowerShell（Windows）：
Get-ChildItem docs -Filter *.md | ForEach-Object {
pandoc $_.FullName -f gfm -o ($_.FullName -replace '\.md$', '.docx')
}
而且 pandoc 只是一个单独的依赖项，放进 CI 毫不费事。下面这个 GitHub Actions 步骤会在每次 push 时重新生成文档的 Word 副本：
- uses: pandoc/actions/setup@v1
- run: |
for f in docs/*.md; do
pandoc "$f" -f gfm --reference-doc=brand.docx -o "out/$(basename "${f%.md}").docx"
done
不少团队用这个模式给 Markdown 维基维护一份 Word 镜像，用于合规审查或交付客户。同一批文件只要转换超过两次，这个脚本立刻回本。
Pandoc 的真实边界（3.7 实测）
我跑的测试是这样的：一个 Markdown 文件，包含一个表格、一个任务列表、行内公式（$E = mc^2$）、一个多行显示公式、一个 Mermaid 流程图和一个 GFM 提示块。用 pandoc 3.7.0.2 转换后，解压 .docx，直接读 word/document.xml。三个发现。
数学公式转 Word：比传言的好得多
文档 XML 里有两个 <m:oMath> 块——每个公式一个。这是 OMML，Word 的原生方程格式。两个公式在 Word 方程编辑器里都完全可编辑，能以印刷质量渲染，复制粘贴到其他 Office 文档也不会丢。
这直接推翻了老教程里至今还能看到的一种说法（直到不久前，我们自己的一篇指南里也有）：复杂 LaTeX 会被栅格化成图片。在当前版本的 pandoc 里不会。标准 LaTeX 数学——分数、求和、希腊字母、上下标——开箱即用地转换为原生方程。公式转 Word 这件事，pandoc 比它的名声靠谱得多。
诚实的边界在这里：pandoc 处理的是标准 LaTeX 数学语法，不是任意 LaTeX。自定义的 \newcommand 宏、TikZ 图形和依赖宏包的环境都过不去。另外如果你的发行版装的是 pandoc 2.x，行为会不同——先跑 pandoc --version 再怪工具。
Mermaid 才是真正的断点
Mermaid 流程图没有变成图表。它以逐字的等宽文本形式输出——原始的 flowchart LR 源码，套着代码块样式。文档 XML 里绘图对象的数量是零。
这个问题比五年前重要得多，因为 AI 助手偏爱 Mermaid。让 ChatGPT 或 Claude 画一个架构概览，回复里大概率带一个 mermaid 代码块。用 pandoc 转换这段对话，Word 文档里出现的就是一段看起来像没删干净的源码。如果这正是你的工作流，我们关于把 ChatGPT 输出导出为 Word 的指南覆盖了 AI 场景的细节。
命令行下有解决办法：mermaid-filter，一个在转换过程中渲染图表的 pandoc 过滤器。它确实能用，但得诚实掂量一下安装成本——它是一个 npm 包，会通过 Puppeteer 拉下来一个无头 Chromium，pandoc 调用也变成 pandoc -F mermaid-filter ...。对每天都要转换图表的文档管线，这笔配置成本摊下来划算；对今天下午就要交的一份报告，它是绕路。
边缘处的小幅保真损失
同一次测试还有两个不那么显眼的发现。GFM 提示块（> [!NOTE]）文字保留，但彩色标注样式丢失——在 Word 里它们就是普通引用块。任务列表项则变成普通列表文本，而不是 Word 的复选框控件。两者都不会毁掉文档，但都抹平了作者大概率是有意选择的格式。如果你的转换还出了别的问题，我们在常见 Markdown 转换问题里整理了高频故障模式。
命令行还是在线转换工具？
测完之后，我真正会采用的决策框架是这张表：
| 你的情况 | 更合适的工具 | 原因 |
|---|---|---|
| 要转很多文件，或反复转同一批文件 | Pandoc | 脚本加 CI 让重复转换零成本 |
| 需要自动套用公司 Word 样式 | Pandoc | --reference-doc 在这方面无可替代 |
| 离线或隔离网络环境 | Pandoc | 单个二进制文件，不联网 |
| 只有一份文档，马上要交 | 在线转换工具 | 零安装，不用管版本 |
| 文档里有 Mermaid 图表 | 在线转换工具 | 图表直接渲染成图表，无需过滤器链 |
| 公司电脑锁了权限，装不了软件 | 在线转换工具 | 浏览器里就能跑 |
| 大量 LaTeX 公式 | 两者皆可 | 现代 pandoc 对标准公式处理得很好，我们也是 |
两条路都是正路。任何周期性运行的管线里，pandoc 都配得上一个位置。而"五分钟内我就要一份 .docx"的一次性场景——尤其牵涉 Mermaid 时——用免费的在线 Markdown 转 Word 转换器能直接拿到一份公式和图表都完好渲染的干净文档，什么都不用装。
常见问题
问：可以不安装任何软件就把 Markdown 转成 Word 吗？
答：命令行做不到——pandoc 必须安装。如果装软件不可行，浏览器端转换器是务实的选择：转换在服务端完成，你直接下载成品 .docx。
问：pandoc 会把 LaTeX 公式转成真正的 Word 方程吗？
答：会。在我们用 pandoc 3.7.0.2 做的测试里，行内和显示公式都变成了原生 OMML 方程，可在 Word 方程编辑器中编辑。例外是非常老的 pandoc 版本和自定义 LaTeX 宏。
问：为什么我的 Mermaid 图表在 Word 里显示成代码？
答：pandoc 把 mermaid 代码块当作字面代码处理，不渲染图表。要么给管线加上 mermaid-filter（需要 Node.js），要么换一个内置 Mermaid 渲染的转换器。
问：怎样保留公司的字体和标题样式？
答：用 --reference-doc=template.docx。在 Word 里把模板的样式改好一次，pandoc 每次转换都会套用。模板里的内容会被忽略，只有样式会被继承。
问：-f markdown 和 -f gfm 有什么区别？
答：markdown 是 pandoc 自家的扩展方言（脚注、引文）；gfm 对应 GitHub、ChatGPT 和多数现代工具的输出——表格、任务列表、删除线。转换 AI 生成或开发者写的 Markdown 时，gfm 的意外更少。
问：pandoc 能把 Word 转回 Markdown 吗？
答：能——把参数反过来：pandoc report.docx -o report.md。往返转换会丢失部分 Word 专有格式（文本框、批注），所以把它当内容迁移用，别指望无损循环。
相关资源
- Markdown 转 Word 完全指南：命令行之外的完整转换方案全景
- ChatGPT 转 Word：AI 生成文档的 Markdown 工作流
- Markdown 转 PDF：交付物是 PDF 时看这篇
- 常见 Markdown 转换问题：表格错乱、编码异常与格式漂移的修法
结论
"在命令行把 Markdown 转成 Word"的正确答案依然是 pandoc——单个文件一条命令，整个文件夹一段脚本，公司样式交给 --reference-doc。我们的测试表明它的公式支持好于口碑：标准 LaTeX 会变成真正可编辑的 Word 方程。
它真正的短板在视觉层：Mermaid 图表会以源码形式落进文档，除非你额外挂上一条基于 Node 的过滤器链。所以按工作流选工具。纯文本文档的周期性管线：用 pandoc 写成脚本。带图表又赶时间的单份文档：在浏览器里转换，公式和流程图都完好保留。
参考资料
- Pandoc User's Guide — 官方手册：读取器、输出器、
--reference-doc与公式处理 - Installing pandoc — 各平台官方安装包
- mermaid-filter — 渲染 Mermaid 图表的社区 pandoc 过滤器
- pandoc/actions — 在 CI 中使用 pandoc 的官方 GitHub Actions
觉得好用？分享给更多朋友吧！
