用Pandoc批量将Markdown转为Word:同名输出与统一样式实践
做技术的人写文档,十个里有八个会选 Markdown——语法轻、不用管排版、还能纳入 Git 管理版本。可稿子一旦要往外交,甲方、评审、出版、留档,基本都只认 Word(.docx)。我这两年陆陆续续帮团队做过好几轮 Markdown 转 Word 的批量迁移,从刚开始一个个复制粘贴到后来写脚本几分钟跑完几百篇,踩过的坑比想象中多得多。这篇就把整套流程完整拆开:怎么用 pandoc 把大量 Markdown 文档批量生成 DOCX,同时保证输出文件名与源文件完全同名,并尽量把图片、表格、公式、编号这些细节不丢地搬进 Word。
如果你只是偶尔转一两篇,随便找个在线工具或者 Typora 导出都能对付;但如果手头是几十上百个 .md 文件,而且每个版本都要重复转一次,那一定要把流程脚本化。这篇文章适合文档工程师、技术负责人、毕业论文党,以及对"批量文档处理"这件事想彻底告别手动操作的人。下面讲的每一段,基本都是从真实项目里踩出来的经验,不是单纯的工具说明书。
1. 先弄清场景:谁需要"批量 Markdown 转 Word"
1.1 三个真实到不能再真实的场景
第一个场景是产品文档团队。我们之前的帮助中心全部用 Git 维护,文章是 Markdown,Pr 合并、review 一套流程走得很顺。但合规部门审批的时候只收 Word,于是每个版本发版前,我们都得把一整批 .md 变成 .docx 提交,少则几十篇,多则上百篇。第二个场景是论文和技术方案。写作阶段大家爱用 Markdown/Typora 写初稿,可学校或评审系统收稿时只认 Word 模板,这时候如果逐篇复制粘贴,格式必然走样,改稿两轮下来心情全毁。第三个场景是知识库内容外发,内部 Wiki 导出 Markdown 给外部客户或合作方时,需要先转成 Word 脱敏交付。
这些场景有一个共同点:量大、重复、格式要求统一。手动复制粘贴根本不可控,一篇文章里十几个标题、几十张图片足以让人崩溃,更别说还要求输出的 Word 必须保留原文件名的对应关系。所以关键词不是"能不能转",而是"能不能稳定地、批量地、可重复地转"。
1.2 "保留同名文件"为什么被反复提起
很多人不理解,转个格式而已,文件名怎么还是刚需?我实际做过的项目里,下游通常有三个依赖:一是审批流程拿文件名做关联,二是合并脚本按文件名排序后再拼总册,三是版本管理里要用 docx 反查对应 md。如果转换工具把输出写成"xxx(已转换).docx",或者集中丢进 output 目录再手工改名,任何一步出错都会让整个交付链条断掉。
正确做法其实特别简单:让 .md 和 .docx 共享同一个文件名主干(file stem),只是扩展名不同。脚本层面就是一个循环取 basename,后面我会给出具体代码。千万别小看这个细节,我第一版脚本就是偷懒统一输出到 output 目录,结果下游同事吐槽了一个星期。
2. 工具选型:为什么全家都用 pandoc
2.1 主流方案速览
先看一张表,是我长期对比后留下的结论:
| 方案 | 批量能力 | 样式定制 | 图片/公式 | 可脚本化 | 综合评价 |
|---|---|---|---|---|---|
| Pandoc | 强 | 强(reference docx) | 强 | 强 | 首选 |
| Typora 导出 docx | 弱(单篇) | 中 | 中 | 基本没有 | 适合随手导一篇 |
| 在线转换网站 | 弱 | 弱 | 不确定 | 无 | 有文件泄露风险,不推荐 |
| Python markdown 库自制 | 中 | 中 | 弱 | 强 | 要自己造轮子,划不来 |
| Apache POI | 中 | 强 | 弱 | 强 | Java 项目里才会考虑,太重 |
Typora 的 Word 导出在不少版本里底层其实也是转换器的封装,单篇用着顺手,但你想在服务器上或者 CI 里批量跑,它给不了你一个干净的命令行接口。在线转换网站就更别说了——文档内容一旦涉及内部信息,上传到第三方站点本身就是安全隐患,这一关基本就能一票否决。
2.2 pandoc 转换链路里到底发生了什么
Pandoc 不是简单地把 Markdown 文本替换成 docx 标签,它的内部结构是这样的:先把 Markdown 解析成一棵 AST(抽象语法树),再把 AST 交给 docx writer 输出成 OOXML(Word 的底层 XML 格式)。这个中间层是 Pandoc 最大的价值所在,因为你可以在 AST 上挂 Lua filter,拦截、改写、插入内容,做到很多原本需要"转换后人工收尾"的工作。
另一个关键认知是:Markdown 里的 # 标题会映射成 Word 内置样式 Heading 1,## 对应 Heading 2,正文对应 Body Text,代码块对应 Source Code,表格对应 Table。最终的视觉样式由 reference docx 决定,也就是说"模板定了,批量文档的排版就定了"。搞懂这两点,后面所有定制都不会跑偏。
3. 从单篇命令到批量脚本:照着抄就能跑
3.1 安装和验证
Windows 下最简单是装个包管理器,choco install pandoc 或者 winget install pandoc,不想折腾就直接去官方 GitHub releases 下载安装包,装完确认 pandoc --version 能正常执行。Linux 上 apt install pandoc 通常版本偏老,建议也从官方拿二进制;macOS 直接 brew install pandoc。有个误区要澄清:转 docx 并不需要安装 TeX 全家桶,很多人一听转换文档以为要装巨无霸,其实 docx writer 是纯 XML 输出,跟 LaTeX 没有任何关系。
验证安装后,建议顺手跑一下 pandoc --list-extensions,看看当前版本默认开启了哪些扩展。后面判断图片、公式问题时会用到,也能避免"这个语法我写了怎么不生效"的莫名情况。
3.2 单篇转换的正确姿势
基础命令长这样:
拆开解释一下:-o 指定输出文件;--reference-doc 指向你自己的样式模板,第一次没有模板也可以先不写;--resource-path 是告诉 pandoc 去哪找图片等资源,通常设成当前目录。如果 Markdown 里有 $x^2$ 这类 LaTeX 公式,默认的 markdown 解析器就支持,pandoc 会直接转成 Word 原生公式(OMML,Open XML Math),在 Word 里可以直接点进去编辑,而不是糊成一张图片。
加目录也很简单,--toc --toc-depth=2。不过要注意,pandoc 生成的 docx 目录是一个 Word 域,打开文档后需要按 Ctrl+A 全选再按 F9 刷新页码,不然页码可能不对。这一点第一次用的人基本都会质疑"目录怎么是空的",其实是没刷新域。
3.3 三种批量脚本实现
先说 Windows 批处理,适合小批量、没装 Python 的环境:
这里 %%~nf 就是去掉扩展名的文件名,它就是"保留同名文件"的机关。|| 后面是失败提示,把错误打印出来而不是静默跳过,批处理才不会变成黑箱。
如果你有几十上百个文件,尤其是 Markdown 散落在多层子目录里,我强烈建议用 Python 脚本管理:
rglob("*.md") 会把当前目录下所有层级的 md 都找出来,md.with_suffix(".docx") 直接保证输出文件和源文件同名,只是后缀不同。注意我把 --resource-path 设成了每个 md 所在目录,这样图片目录跟随 md 文件放置的方案就不会摔跤。
macOS/Linux 下就算不用 Python,shell 一行也很直白:
3.4 批量执行前的一个小习惯
我每次跑全量转换前都会先做 dry-run,也就是只打印将要执行的命令,不真正执行。检查清单就三行:文件数量对不对、有没有误包含草稿目录、文件名重名情况。Python 脚本里把 subprocess.run 换成 print(" ".join(cmd)) 就能模拟一遍,成本几乎为零,但能省掉大量事故排查时间。实际跑转换时再换回真执行。
还有一点经验:第一次跑完不要急着打包交付,先随机抽三篇打开看,重点看下一节那几个高频坑。批量转换最怕的不是转换失败,而是转换"成功"了但内容悄悄坏了一部分。
4. 批量转完必踩的坑,附完整排查链路
4.1 图片路径全断,Word 里红叉一片
这是我们团队踩得最深的一个坑,也是最容易复现的。症状是转换命令没有报错,但打开 docx 后图片全是红叉或空白,只剩下替代文字。排查链路一般是这样的:
第一步,先在 md 所在的目录下手动执行一次 pandoc,如果图片正常,说明 Markdown 里相对路径写的是对的。第二步,换到脚本从根目录运行时图片断了,基本就是工作目录问题——pandoc 是按"当前进程的工作目录"来解析相对路径的,脚本跑在根目录,它当然找不到子目录下的 imgs 文件夹。第三步,给命令加上 --resource-path=md所在目录,或者在 Python 脚本里按 md.parent 动态设置,问题就消失了。
这里有条团队级经验:从一开始就规定 Markdown 里的图片一律用相对路径,且图片目录和 md 文件同级,脚本里统一把 resource-path 指向每个 md 的 parent。这样无论文件怎么迁移、脚本在哪跑,都不会再断。如果是外链图片,建议先下载到本地 assets 再转,内网图尤其要处理,否则转换过程要么卡死要么直接失败。
4.2 表格列宽失控和标题编号错乱
经常有人搜"word 表格列宽无法拖动",转换过来的表格尤其容易撞上这个问题。原因不复杂:Markdown 的 pipe table 本身不含列宽信息,Word 只能按内容自适应,遇到长文本或宽表就撑到页面外。三个处理办法:一是改 reference docx 里的 Table 样式,把表格首选宽度设为 100%;二是源文件里对特别复杂的表格换成 grid table 或 HTML 表格,pandoc 转 docx 时也能识别;三是写一个 Lua filter 在 AST 上直接给 Table 节点设置列宽。最懒的修法是在 Word 里手动调一次并把表格布局改成"自动调整",但批量文档逐个这么调就没意义了。
标题编号是另一个高频坑,尤其是"dify markdown 转 word 中序号自动编号"这类问题。如果你的 Markdown 标题里已经写了"1.1 绪论"这种手写编号,到了 Word 里又想开自动多级编号,出来的效果就是"1.1 1.1 绪论",双重编号。我的原则是二选一:源文件里不带编号,完全交给 Word 的多级列表自动生成;源文件已经带编号,就关掉 Word 自动编号。两者同时上,必然乱。
4.3 中文乱码、空白页和公式的"降级"处理
Pandoc 默认的 reference docx 里 Normal 样式字体是 Calibri,中文会走系统 fallback,Windows 上通常是宋体,但行距、字重、宽窄都不可控。所以要改 reference docx 里 Normal 样式的东亚字体(第五节讲具体方法),统一设成宋体或仿宋。这不是可选项,是刚需。
"word 最后一页死活删不掉"算是老熟人了。转换后的文档末尾如果多出一个空白页,多半是 Markdown 末尾的空行转成了 Normal 段落,而模板里正文段落的段后间距较大,直接把内容顶到了下一页。排查时先删掉源文件尾部多余换行,再看模板样式段后间距,实在不行就在 Word 里把光标放到最后按 Delete。
公式方面要提前打预防针。$...$ 和 $$...$$ 转成 Word 原生公式一般没问题,但如果你大量使用 aligned 这类 LaTeX 环境,或者自定义了很多宏,个别 pandoc 版本可能直接就转换失败,或者降级成普通文本。批量之前一定要抽两篇带公式的文档试转换,确认公式在 Word 里能双击编辑,而不是变成静态图片。"word 公式转 latex" 之所以被天天搜,就是因为这个方向绕回来很痛苦,尽量不要在转换前就把公式搞复杂。
代码块也要留意。pandoc 转 docx 时代码块映射为 Source Code 样式,默认白底等宽字体,可读性够用。想带语法高亮可以试试 --highlight-style=tango 这类参数,不过不同版本对 docx 高亮的支持有差异,以实测为准。多数交付场景里,保持统一等宽字体反而更稳重。
5. 用 reference docx 统一样式,让批量文档像一个妈生的
5.1 提取 Pandoc 默认模板
先说怎么拿到 reference docx。老版本命令是 pandoc -o custom-reference.docx --print-default-data-file=reference.docx,新版本更直接:
生成的 custom-reference.docx 用 Word 打开后,能看到一个带示例内容的文档,里面定义了 Normal、Heading 1 到 6、Body Text、First Paragraph、Table、Source Code 等一堆样式。注意:你在里面写的任何正文内容,都不会出现在最终转换结果里,它只是个"样式仓库",pandoc 只读取里面的样式定义。这个点我见过无数人第一次搞混。
5.2 在 Word 里调整模板
接下来按自己需求改样式。以中文技术文档为例,我通常会改这几处:Normal 样式设 Times New Roman + 宋体,小四,行距 1.3 倍;Heading 1 到 Heading 3 设黑体或微软雅黑,调整段前段后;表格样式做三线表;页边距设 A4。全部改完保存,批量脚本里把 --reference-doc 指向这个文件,所有输出 docx 都会继承同一套排版。
这里顺便解释一个 Word 老问题:"标题居中后位置偏右"。如果你在模板里发现居中标题总是偏右,多半是样式里带了首行缩进或制表位,把段落缩进清零、制表位删掉就正常了。这类问题出在模板上远比出在每篇文档上好修。你在 reference docx 里把坑填平,后面几百篇文件自动受益。
5.3 用 python-docx 改模板,告别手工重复
如果只是改几个样式,Word 里点几下就行。但如果你要统一 20 多个标题样式的字体、字号、颜色,手工点会崩溃。这时候就可以用 python-docx 直接改模板 XML:
rFonts 里的 w:eastAsia 属性,就是 Word 中"中文字体"的落点。只设置 font.name 是不够的,这也是很多人改了模板却发现中文没生效的原因。这一行代码,比你在 Word 界面里找半天"中文字体"选项要快得多。
5.4 封面、页眉页脚、强制分页
如果你需要封面和页眉页脚,直接在 reference.docx 里做好,转换出来的每篇 docx 都会带上。目录用前面说的 --toc 生成,打开 Word 后全选按 F9 刷新域即可。每章强制分页可以在 Markdown 里插入一小块原生 OpenXML:
默认 markdown 解析器就支持这种 raw attribute 写法,pandoc 在输出 docx 时会把这段直接写进 XML,效果就是一章结束强制另起一页。如果你不想在源文件里掺这些标记,也可以用 Lua filter 在每个一级标题前自动插入分页符,原理一样。
最后说一个进阶思路:如果公司已经有成熟的 Word 模板(带封面、页眉、水印),直接拿它当 reference 不一定能行,因为模板里的样式名和 pandoc 映射的样式名可能对不上,转出来会崩。稳妥的做法是用 pandoc 默认 reference 做底,把公司模板里的封面、页眉、页脚复制过来,而不是反过来改。
我自己的项目里,最后把整套流程接进了 CI:每次合入代码,流水线自动跑一遍批量转换,输出 docx 作为交付附件。如果你在 Coze、Dify 这类工作流平台里搭文档自动化,大概率会发现底层节点就是调 pandoc,把这套脚本包成一个接口丢进去也一样能用。从最初手动转到后来全程自动化,最大的体会是——批量转换这件事,真正的成本不在转换本身,而在那些"转完才发现图片断了、编号乱了、字体变了"的返工。所以现在团队里立了个规矩:任何新文档转换需求,必须先转三篇样章,确认图片、表格、编号、公式四项没问题,再放开跑全量。这套检查单看着笨,实际上最省时间。如果你也正被 Markdown 转 Word 折磨,建议直接照上面的脚本搭一套,第一次花半天,之后每轮能省一天。