使用 Pandoc 将含复杂公式的 Word 文档无损转换为 MD（Windows 避坑指南）

实战记录：使用 Pandoc 将含复杂公式的 Word 文档无损转换为 Markdown（Windows 避坑指南）

在学术写作和知识管理中，我们经常需要将 Word 文档迁移到 Markdown 格式。对于纯文本内容，转换非常简单；但一旦文档中包含复杂的数学公式 （尤其是带有中文说明的公式）以及大量图片时，转换过程往往会遇到各种"玄学"报错。

本文基于一次真实的毕业论文转换经历，记录了如何在 Windows 环境下利用 Pandoc 实现 Word 到 Markdown 的高质量转换，并解决了常见的编码冲突与文件丢失假象。

1. 核心工具与环境准备

为什么选择 Pandoc？

Pandoc 被称为文档转换界的"瑞士军刀"。它不仅能处理文本，最核心的优势在于能解析 Word 内部的 XML 结构，将其中的公式转换为 LaTeX 语法，从而在 Markdown 中保留数学语义，而不是变成一张模糊的图片。

安装步骤（Windows）

1. 下载 ：访问 Pandoc GitHub Releases 页面，下载最新的 .msi 安装包。
2. 安装：运行安装包，默认路径即可。
3. 验证 ：打开 CMD 或 PowerShell，输入 pandoc -v。如果显示版本号，说明环境变量已自动配置成功。

注意 ：如果提示"不是内部或外部命令"，请手动将 Pandoc 的安装路径添加到系统的 Path 环境变量中，并重启终端。

2. 基础转换命令

假设你的 Word 文档名为 input.docx，且包含图片，希望输出为 output.md 并将图片提取到 images 文件夹。

标准命令如下：

pandoc -f docx -t markdown_strict --extract-media=./images -o output.md input.docx

• -f docx: 指定输入格式为 Word。
• -t markdown_strict: 输出严格的 Markdown 格式（兼容性最好）。
• --extract-media=./images: 关键参数 。Word 中的图片会被提取并存放到当前目录下的 images 文件夹中，Markdown 里的链接会自动指向这些图片。
• -o output.md: 指定输出文件名。

3. 遇到的"坑"与解决方案

在实际转换一篇包含大量数学推导的毕业论文第三章时，我遇到了两个典型问题。

问题一：终端报错 hPutChar: invalid argument

现象：

命令行输出一堆警告后，突然报错退出：

pandoc: <stderr>: hPutChar: invalid argument (Invalid argument)

原因分析：

这是 Windows CMD 的经典编码冲突。Pandoc 内部使用 UTF-8 编码，而 Windows 中文版 CMD 默认使用 GBK 编码。当 Pandoc 试图向终端输出包含生僻字或特殊符号的警告信息（Warning）时，字符无法映射，导致程序崩溃或中断。

解决方案：

我们不需要看那些警告信息，直接将其屏蔽即可。在命令末尾加上 2>nul（Windows 下屏蔽错误输出）：

pandoc ... -o output.md input.docx 2>nul

问题二：明明报错了，为什么找不到生成的 MD 文件？

现象：

终端报错后，去文件夹里找 output.md，发现根本没有这个文件（或者看起来没生成）。

真相：

其实文件已经生成了 ！

Pandoc 的执行逻辑是流式的。即使最后因为输出警告信息导致终端报错，之前的写入操作往往已经完成。

排查方法：

1. 刷新资源管理器 ：按 F5 刷新文件夹。
2. 检查扩展名：确保资源管理器开启了"显示文件扩展名"。有时候它显示为"第三章"类型是"Markdown 文件"，容易被忽略。
3. 命令行确认 ：在终端输入 dir *.md，你会惊讶地发现文件其实静静地躺在那里。

问题三：复杂公式乱码或转换失败

现象：

警告信息显示 Could not convert TeX math...。

打开生成的 MD 文件，发现部分公式变成了类似 \text{伪}^{\text{鈭梷}}... 的乱码代码。

原因分析：

Word 的公式编辑器（Equation Editor）底层结构与 LaTeX 并不完全对应。特别是当公式中混排了中文（如"设 α \alpha α 为..."），或者使用了特殊的上下标结构时，Pandoc 的转换器可能会"罢工"，直接吐出底层的 TeX 源码。

优化建议：

为了防止长公式被强制换行导致结构破坏，建议加上 --wrap=none 参数。

最终推荐使用的"完美"命令：

pandoc -f docx -t markdown_strict --wrap=none --extract-media=./images -o 第三章.md 第三章.docx 2>nul

4. 总结与后续处理

通过上述命令，你可以成功将 Word 转换为 Markdown。对于转换后的结果，有两点建议：

1. 图片检查 ：检查 images 文件夹，确认所有插图都已导出，且 MD 文件中的引用路径正确。
2. 公式微调：由于 Word 公式转 LaTeX 不可能 100% 完美，对于报错的复杂公式，建议在 Typora 或 VS Code 中打开 MD 文件，手动修正那些渲染失败的 LaTeX 代码块。

虽然需要少量人工校对，但这比重新手打一遍公式已经节省了 90% 的时间。