解决 Pandoc 执行 mermaid-filter 时 “createProcess: invalid argument (Exec format error)” 错误

在使用 Pandoc 结合 mermaid-filter 生成包含 Mermaid 流程图的 Word 或 PDF 文档时，很多 Windows 用户会遇到如下报错：

createProcess: invalid argument (Exec format error)

这通常是因为 filter 的安装方式或调用方式不正确。本文将分析原因，并分享几种解决方案，帮助你顺利在 Windows 上用 Pandoc 支持 Mermaid。

---

一、问题背景

Pandoc 是一个强大的文档转换工具，支持 Markdown、Word、PDF 等多种格式转换。Mermaid 是一种基于文本的流程图、时序图等可视化工具。mermaid-filter 是 Pandoc 的一个 filter，可以让你在 Markdown 文档中插入 Mermaid 代码块，自动生成图表。

典型用法如下：

pandoc input.md -o output.docx --filter=mermaid-filter

但在 Windows 上，你可能会遇到 Exec format error，这是因为 Pandoc 找到的 mermaid-filter 文件无法直接执行。

---

二、原因分析

1. filter 文件类型不正确

• mermaid-filter 可能是一个 JS 文件（如 mermaid-filter.js），需要通过 node 命令运行。
• 如果你用 npm 安装，Windows 会自动生成一个 mermaid-filter.cmd 批处理文件，可以直接运行。
• 如果 filter 是 Python 脚本（比如 pandoc_mermaid_filter.py），需要用 python 命令运行。

2. 路径和环境变量配置不当

• 如果 filter 文件不在 PATH 环境变量中，或者你指定的路径不是可执行文件，Pandoc 就会报错。
• 直接指定 JS 文件（mermaid-filter.js）或 Python 文件（*.py）会导致 “Exec format error”。

---

三、解决方案

方法一：正确使用 npm 安装的 mermaid-filter

1. 安装 mermaid-filter

npm install -g @mermaid-js/mermaid-filter

2. 检查可执行文件

在 C:\Users\<你的用户名>\AppData\Roaming\npm 下，应该有 mermaid-filter.cmd 文件。

3. 调用方式

如果 npm 目录已加入 PATH，可以直接写：

pandoc input.md -o output.docx --filter=mermaid-filter

否则，指定完整路径：

pandoc input.md -o output.docx --filter="C:\Users\<你的用户名>\AppData\Roaming\npm\mermaid-filter.cmd"

注意：不要直接指定 mermaid-filter.js，必须用 .cmd 文件。

---

方法二：使用 Python 版本的 mermaid-filter

1. 安装 Python 版本

pip install pandoc-mermaid-filter

2. 使用方式

如果安装成功，可以直接用：

pandoc input.md -o output.docx --filter=pandoc_mermaid_filter

或者指定脚本路径：

pandoc input.md -o output.docx --filter="python C:\路径\到\pandoc_mermaid_filter.py"

---

方法三：检查 PATH 环境变量

确保你的 npm 安装目录已加入系统 PATH：

1. 右键“此电脑” → “属性” → “高级系统设置” → “环境变量”
2. 编辑系统变量 PATH，添加 C:\Users\<你的用户名>\AppData\Roaming\npm

---

方法四：使用 Lua Filter

如果你不想安装 Node.js 或 Python filter，可以试试 Pandoc 的 Lua filter。推荐 pandoc-mermaid 项目。

用法：

1. 下载 mermaid.lua 到本地

2. 执行：

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

---

四、常见问题 Q&A

Q1: 直接指定 JS 文件为什么不行？

因为 Pandoc 需要 filter 是可执行文件或带有 shebang 的脚本。JS 文件本身不能在 Windows 下直接运行，必须通过 node 执行，或者用 npm 安装后生成的 .cmd 文件。

Q2: Python 版本支持哪些格式？

Python 版的 pandoc-mermaid-filter 支持生成 PNG、SVG 等图片嵌入到 Word、PDF、HTML 等 Pandoc 支持的格式。

Q3: Lua filter 有什么局限？

Lua filter 依赖于 Pandoc 的内置机制，功能略有限，但无须额外安装 Node.js 或 Python 环境，适合轻量需求。

---

五、总结与建议

• 优先推荐：用 npm 安装 mermaid-filter，确保调用的是 .cmd 文件。
• 兼容性好：用 Python 版本的 filter，适合更复杂的需求。
• 轻量方案：用 Lua filter，免除环境配置困扰。
• 遇到问题时：检查 PATH，确认 filter 文件类型和路径，必要时加上完整路径和后缀。

---

六、参考链接

• Pandoc 官方文档
• mermaid-js/mermaid-filter
• pandoc-mermaid-filter (Python)
• pandoc-mermaid (Lua)

---

如有疑问，欢迎留言讨论或贴出你的安装截图、命令行输出，我会帮你进一步分析！