Word怎么转Markdown？从OOXML结构到pandoc转换的完整原理

把 .docx 转成 Markdown 看起来很简单，但实践中总会遇到：表格错位、图片丢失、层级错乱、代码块里的内容被拼成一行。要理解为什么，得先明白 .docx 到底是什么——它不是一个"纯文本文件"，而是一个 OOXML 压缩包。本文从 docx 的内部结构讲起，讲清 Word 排版与 Markdown 结构化语法之间的映射关系，再落到 pandoc 这类转换器的处理流程，附可运行命令，适合想搞懂"文档互转"底层原理的开发者。

一、.docx 不是文本文件，而是一个 ZIP 包

很多人以为 docx 是"Word 保存的一种文本格式"，实际上 .docx 是一个 ZIP 压缩包。把后缀改成 .zip 解压，里面是这样的：

document.xml   # 正文内容（段落、文字、表格）
styles.xml     # 样式定义（标题、正文、引用等）
media/         # 内嵌图片
docProps/      # 元数据

document.xml 里每个段落都是一个 <w:p> 节点，每个文字段是一个 <w:r> （run）。层级关系用 <w:pStyle w:val="Heading1"/> 这样的样式引用标注。

也就是说：Markdown 记录"标题/正文/列表/表格"的语义，而 docx 用 XML 表达同样的语义，但打包进了 ZIP。 转换的本质，就是"从 XML 树，映射成 Markdown 记号"。

二、docx 到 Markdown 的字段映射

docx 元素	Markdown 语法	映射要点
Heading1 样式	#	取样式名
Heading2	##	同上
正文段落	普通段落	去掉段落内多余 run
Bold run	**加粗**	识别 w:b
表格	markdown 表格	逐行逐格
图片		需要先抽取

关键结论：Markdown 是纯文本语义（#、**、|），docx 是 XML 语义（pStyle、w:b），之间没有"一步到位"的神奇转换，全是在语义树上做一一映射 + 处理边界情况（比如合并单元格）。

三、pandoc：文档转换的瑞士军刀

pandoc 是处理这类转换最成熟的工具，它最近接入了一个通用文档模型（Pandoc AST）——先把 docx 解析成一个中间树（AST），再渲染成 Markdown。这个两阶段设计是它"能相互转换那么多格式"的关键。

# Word 转 Markdown（最常见用法）
pandoc input.docx -o output.md

# 保留表格
pandoc input.docx -t markdown --toc -o output.md

# 指定输出扩展（表格强制用 markdown 表格）
pandoc input.docx -f docx -t gfm -o output.md

-t gfm 用 GitHub 风格 Markdown，表格输出更标准。

五、为什么转换后有各种"坑"

5.1 表格错位

docx 表格支持合并单元格（colspan/rowspan），但 Markdown 纯文本表格不支持合并，pandoc 只能以某种方式展开或降级，容易丢对齐。

5.2 标题层级不稳

如果 docx 里没有用样式（而是手动放大字号、加粗），pandoc 无法识别"这是 Heading3"，输出就变成普通段落或只有加粗。用样式的 Word 转得准，纯手排的会乱。

5.3 图片路径

Markdown 的图片是外部引用，pandoc 需要 --extract-media 把图片导出到本地，否则 markdown 里的图片路径是空的。

# 同时导出图片
pandoc input.docx --extract-media=./media -o output.md

六、落地：自建 pandoc vs 在线 tool

维度	自建 pandoc	在线工具
安装	需装 pandoc	上传即用
参数控制	完全可控（gfm/表格/图片导出）	封装了常用配置
批量	脚本化	单次
环境	需维护	零

比如 91aitool.cn 的 Word转Markdown 工具就走服务端 pandoc 方案，上传 .doc/.docx 直接输出 Markdown，支持图片导出，适合不想自己装 pandoc、偶尔转一次的场景。

七、常见问题

为什么转出来标题变成正文一长段？

因为原 Word 用的是手动放大字号，不是标题样式。重建后用样式，转换就会正确识别标题层级。

表格转出来乱了？

合并单元格是 docx 表格的难点，pandoc 无法完全还原合并单元格，只能降级或展开。简单表格问题不大。

图片怎么导出？

用 pandoc --extract-media=./media input.docx -o output.md，图片会单独导出。

docx 和 doc 有区别吗？

docx 是 OOXML（ZIP 包），doc 是二进制格式，pandoc 对 doc 支持有限，很多场景需要先转 docx。

八、总结

Word 转 Markdown 的本质，是把 OOXML 语义树映射成 Markdown 文本记号。搞懂 .docx = ZIP 包、Heading=样式引用，就知道为什么"用样式的 Word 转得好、纯手工排版会乱"。pandoc 用中间 AST 把这一映射做得很通用，是这类转换的标准工具。

参考资料

• OOXML 规范（ECMA-376）
• pandoc 官方文档：https://pandoc.org/
• pandoc docx reader/writer 源码与变量说明