目录

1. 核心原理与工具链介绍
2. 第一步：安装 Pandoc（万能文档转换器）
   2.1 下载与安装
   2.2 验证安装
   2.3 常见问题
3. 第二步：安装 Node.js 与 npm（运行 mermaid-filter 的环境）
   3.1 下载与安装
   3.2 验证安装
   3.3 配置国内镜像加速（可选）
4. 第三步：全局安装 mermaid-filter（Mermaid 渲染过滤器）
   4.1 使用 npm 安装
   4.2 验证安装及查找可执行文件路径
   4.3 常见安装错误及解决
5. 第四步：在 VS Code 中配置一键转换任务
   5.1 打开项目文件夹
   5.2 创建 .vscode/tasks.json
   5.3 编写任务配置（Windows 版）
   5.4 任务配置详解
   5.5 运行任务并生成 Word
6. 第五步：处理 Mermaid 语法错误（最关键的一步）
   6.1 错误现象
   6.2 错误原因分析
   6.3 常见语法错误清单及修复方法
   6.4 使用在线工具验证 Mermaid 代码
7. 第六步：优化转换效果
   7.1 调整图片尺寸
   7.2 设置 Word 样式
   7.3 批量转换多个文件
8. 备选方案（当 mermaid-filter 无法工作时）
   8.1 方案 A：使用 Markdown Preview Enhanced 导出 HTML，再用 Word 打开
   8.2 方案 B：使用 Typora 付费版直接导出 Word
   8.3 方案 C：手动截图插入 Word
9. 常见错误汇总与终极排错指南
10. 总结与建议

---

1. 核心原理与工具链介绍

将包含 Mermaid 代码的 Markdown 转换为 Word 并保留图形，本质上需要完成两个任务：

• 将 Mermaid 代码块渲染为图片（通常是 PNG 或 SVG）。
• 将 Markdown 格式（标题、列表、表格等）转换为 Word 的 .docx 格式。

业界标准工具组合为：Pandoc + mermaid-filter。

• Pandoc：命令行文档转换工具，支持 Markdown → .docx，并允许通过“过滤器”在处理过程中修改文档内容。
• mermaid-filter：一个 Pandoc 过滤器，它会找到文档中的所有 Mermaid 代码块，调用 Mermaid 渲染引擎将其生成图片，然后将图片嵌入到文档中，再交给 Pandoc 继续转换。

因此，整个流程是：
Markdown 文件 → Pandoc 调用 mermaid-filter → mermaid-filter 将每个 Mermaid 代码块替换为图片 → Pandoc 生成 .docx。

本文会指导您在 Windows 上完整搭建这一工具链，并在 VS Code 中配置一键运行任务。

---

2. 第一步：安装 Pandoc（万能文档转换器）

2.1 下载与安装

1. 打开浏览器，访问 Pandoc 官方网站：https://pandoc.org/installing.html
2. 找到 Windows 安装包（通常是一个 .msi 文件，例如 pandoc-3.1.12-windows-x86_64.msi）。
3. 下载该文件到本地。
4. 双击运行安装程序。
5. 在安装向导中，务必勾选“Add Pandoc to PATH”（默认可能已勾选），这样在命令行中才能直接调用 pandoc 命令。
6. 其余选项保持默认，一路 “Next” 完成安装。

2.2 验证安装

1. 按 Win + R，输入 cmd 并回车，打开命令提示符。
2. 输入以下命令并回车：

   pandoc --version
   

3. 如果看到类似输出：

   pandoc 3.1.12
   Features: +server +lua ...
   

   说明 Pandoc 安装成功。

2.3 常见问题

• 错误：‘pandoc’ 不是内部或外部命令
  原因：安装时未勾选 “Add to PATH”，或者安装后未重启命令行。
  解决办法：

  1. 重新运行 Pandoc 安装程序，选择 “Repair” 并确保勾选 “Add to PATH”。
  2. 或者手动将 Pandoc 安装目录（如 C:\Program Files\Pandoc\）添加到系统环境变量 PATH 中。
  3. 关闭所有命令行窗口，重新打开后再试。

• 安装后重启了电脑仍无效
  检查系统环境变量：右键 “此电脑” → 属性 → 高级系统设置 → 环境变量 → 在系统变量中找到 Path，编辑，添加 C:\Program Files\Pandoc\。确定后重新打开命令行。

---

3. 第二步：安装 Node.js 与 npm（运行 mermaid-filter 的环境）

mermaid-filter 是基于 Node.js 的工具，因此必须先安装 Node.js（npm 是 Node.js 的包管理器）。

3.1 下载与安装

1. 访问 Node.js 官网：https://nodejs.org/
2. 下载 LTS 版本（长期支持版，例如 20.x.x 或 22.x.x），Windows 选择 .msi 安装包。
3. 运行下载的 .msi 文件。
4. 在安装向导中，务必勾选 “Automatically install the necessary tools”（会自动安装构建工具，但即使不勾选，只要勾选 “Add to PATH” 即可）。
5. 重点：勾选 “Add to PATH”（通常默认勾选）。
6. 完成安装，重启电脑（确保 PATH 变量生效）。

3.2 验证安装

重新打开命令提示符，输入：

node --version
npm --version

正常应显示：

v22.14.0
10.9.2

若显示版本号，则安装成功。

3.3 配置国内镜像加速（可选）

由于默认 npm 源在国外，下载 mermaid-filter 可能较慢。建议配置淘宝镜像：

npm config set registry https://registry.npmmirror.com

验证：npm config get registry 应输出淘宝镜像地址。

---

4. 第三步：全局安装 mermaid-filter

4.1 使用 npm 安装

在命令提示符中执行：

npm install -g mermaid-filter

• -g 表示全局安装，这样在任何目录下都可以调用 mermaid-filter 命令。
• 安装过程需要联网，会下载 mermaid-filter 及其依赖（包括 puppeteer，后者会下载 Chromium 浏览器内核，约 150 MB）。第一次安装较慢，请耐心等待（约 1-5 分钟，视网络而定）。

安装成功后会显示类似：

added xxx packages in xx seconds

4.2 验证安装及查找可执行文件路径

验证命令：

mermaid-filter --help

如果输出帮助信息（用法说明），说明安装成功且 PATH 已包含。

但如果提示 'mermaid-filter' 不是内部或外部命令，则说明全局安装的 bin 目录未在 PATH 中。此时我们需要找到它的实际位置。

查找路径：

npm config get prefix

输出例如：C:\Users\你的用户名\AppData\Roaming\npm
那么 mermaid-filter.cmd 文件就在该目录下。完整路径为：

C:\Users\你的用户名\AppData\Roaming\npm\mermaid-filter.cmd

（注意：Windows 下可执行文件是 .cmd 后缀）

测试能否直接运行：

"C:\Users\你的用户名\AppData\Roaming\npm\mermaid-filter.cmd" --help

若成功，则记住此路径，后续在 VS Code 任务中需要使用绝对路径。

4.3 常见安装错误及解决

错误信息	原因	解决方案
'npm' 不是内部或外部命令	Node.js 未安装或 PATH 未生效	重装 Node.js，确保勾选 “Add to PATH”，重启电脑
npm ERR! network timeout	网络慢或默认源被墙	配置淘宝镜像：npm config set registry https://registry.npmmirror.com 后重试
Error: Could not find Chromium	puppeteer 下载 Chromium 失败	手动设置 Chromium 环境变量，或忽略脚本：npm install -g mermaid-filter --ignore-scripts，然后手动安装 puppeteer 的 Chromium（较复杂，建议重试或换网络）
permission denied (非 Windows)	权限不足	使用 sudo npm install -g mermaid-filter

注意：即使 Chromium 下载失败，mermaid-filter 命令本身可能仍会安装，但运行时可能报错。如果遇到渲染错误，可尝试重新安装并确保网络畅通。

---

5. 第四步：在 VS Code 中配置一键转换任务

完成 Pandoc、Node.js、mermaid-filter 的安装后，我们将在 VS Code 中配置一个任务，实现按一个快捷键就完成转换。

5.1 打开项目文件夹

• 启动 VS Code。
• 点击 文件 → 打开文件夹，选择您存放 Markdown 文件的目录（例如 D:\my-docs）。
• 确保左侧资源管理器中能看到您的 .md 文件。

5.2 创建 .vscode/tasks.json

1. 按 Ctrl+Shift+P 打开命令面板。
2. 输入 Tasks: Configure Task，选择它。
3. 然后选择 Create tasks.json file from template，再选择 Others。
4. VS Code 会自动在项目根目录创建 .vscode 文件夹及其中的 tasks.json 文件，并打开它。

5.3 编写任务配置（Windows 版）

将 tasks.json 中的内容替换为以下代码（请根据您的用户名和 mermaid-filter 实际路径修改）：

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Convert MD to Word with Mermaid",
            "type": "shell",
            "command": "pandoc",
            "args": [
                "${relativeFile}",
                "-o",
                "${relativeFileDirname}\\${fileBasenameNoExtension}.docx",
                "--filter",
                "C:\\Users\\您的用户名\\AppData\\Roaming\\npm\\mermaid-filter.cmd"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "presentation": {
                "reveal": "always",
                "panel": "shared",
                "clear": true
            },
            "problemMatcher": []
        }
    ]
}

重要：将 您的用户名 替换为您电脑的实际用户名（例如 xue.hy）。路径中的反斜杠要写成双反斜杠 \\ 以符合 JSON 转义规则。

如果您的 mermaid-filter 可以直接通过命令名调用（即 PATH 已包含），则可以将 "--filter", "C:\\Users\\..." 简化为 "--filter", "mermaid-filter"。但从您之前的错误看，系统找不到该命令，所以推荐使用绝对路径。

5.4 任务配置详解

• "label"：任务名称，会在运行任务时显示。
• "type": "shell"：在系统 Shell（Windows 中是 PowerShell 或 CMD）中执行。
• "command": "pandoc"：要运行的程序。
• "args"：参数列表。
  • ${relativeFile}：当前在 VS Code 中打开的文件的路径（相对于工作区根目录）。
  • -o：输出参数。
  • ${relativeFileDirname}\\${fileBasenameNoExtension}.docx：输出文件路径，与源文件同目录、同命名，扩展名为 .docx。
  • --filter：指定 Pandoc 过滤器。
  • 后面是过滤器的可执行文件路径。
• "group": { "kind": "build", "isDefault": true }：将此任务设为默认构建任务，便于使用快捷键 Ctrl+Shift+B 直接运行。
• "presentation"：控制任务运行时终端的行为，"reveal": "always" 表示总是显示终端面板，"clear": true 表示每次运行前清除之前的输出。
• "problemMatcher": []：不进行问题匹配（因为 Pandoc 的输出格式不是标准编译错误）。

5.5 运行任务并生成 Word

1. 在 VS Code 中打开您的 Markdown 文件（例如 CP平台上对系统式样进行功能差分.md）。
2. 按快捷键 Ctrl+Shift+B。
3. 底部会弹出终端面板，显示 Pandoc 运行日志。如果一切正常，会看到类似：

   [INFO] 生成单个 mermaid 图表...
   [INFO] 转换完成。
   

4. 转换完成后，在文件资源管理器中，与源文件同目录下会生成一个同名的 .docx 文件。
5. 双击用 Word 打开，检查 Mermaid 图形是否已正确渲染为图片。

如果运行后出现错误，请继续阅读下一章。

---

6. 第五步：处理 Mermaid 语法错误（最关键的一步）

即使工具链安装正确，转换仍可能因为 Markdown 中的 Mermaid 代码语法错误而失败。您之前遇到的错误正是这种情况。

6.1 错误现象

终端输出类似：

Error running filter mermaid-filter: 
Error: Evaluation failed: Error: Parse error on line 7...
... 动作: 存储DTC, 点亮警告灯 ...
Expecting 'SPACE', 'NL', ... got 'DESCR'

Pandoc 任务返回退出码 1，Word 文件未生成。

6.2 错误原因分析

Mermaid 语法非常严格。常见的错误包括：

• 在状态图（stateDiagram）的描述文本中直接使用了中文冒号、逗号，且未用双引号包裹。
  例如：
  FailedAll: 动作: 存储DTC, 点亮警告灯
  解析器会把冒号当作语法标记，导致错误。

• 节点标签中包含未转义的特殊字符，如方括号、花括号、竖线等。

• 缺少必要的空格或换行。

• 使用了 Mermaid 版本不兼容的语法（例如老版本不支持 stateDiagram-v2 中的某些特性）。

6.3 常见语法错误清单及修复方法

错误代码示例	正确写法	说明
stateDiagram S: 状态: 描述	stateDiagram S: "状态: 描述"	描述中的冒号需加引号
graph TD A[你好！] --> B	A["你好！"] --> B	感叹号等特殊字符需引号
sequenceDiagram A->B: 消息"hello"	A->B: "消息\"hello\""	引号内再含引号需转义
classDiagram class MyClass{ +int age }	需要每行正确缩进，类体内不要多余空格	参考官方文档
gantt dateFormat YYYY-MM-DD title 项目 section A 任务 :a, 2023-01-01, 3d	必须严格按照甘特图语法，日期格式正确	检查官方示例

通用修复原则：

• 凡是描述文本中包含标点符号（冒号、逗号、分号、感叹号、问号）或中文字符，都使用双引号括起来。
• 避免在节点 ID 中使用空格，用下划线或驼峰命名。
• 每个语句独占一行。
• 使用在线编辑器验证（推荐 https://mermaid.live/）。

6.4 使用在线工具验证 Mermaid 代码

1. 打开浏览器访问 https://mermaid.live/。
2. 将您怀疑有问题的 Mermaid 代码块（从 ```mermaid 到 ` ````之间的内容）复制到左侧编辑区。
3. 右侧会实时渲染。如果出现错误，会提示行号和错误信息。
4. 根据提示修改，直到右侧正常显示图形。
5. 将修正后的代码复制回您的 Markdown 文件，保存后再运行转换任务。

针对您之前的错误：
在状态图中找到类似 FailedAll: 动作: 存储DTC, 点亮警告灯 的行，改为 FailedAll: "动作: 存储DTC, 点亮警告灯" 即可。

---

7. 第六步：优化转换效果

7.1 调整图片尺寸

mermaid-filter 默认生成的图片宽度为 800 像素。您可以通过环境变量或参数调整。
方法：在运行 Pandoc 命令时添加 --metadata= mermaid-width:1200。
修改 tasks.json 中的 args 数组，在 --filter 之前加入：

"--metadata", "mermaid-width:1200",

完整示例：

"args": [
    "${relativeFile}",
    "-o",
    "${relativeFileDirname}\\${fileBasenameNoExtension}.docx",
    "--metadata", "mermaid-width:1200",
    "--filter", "C:\\Users\\...\\mermaid-filter.cmd"
]

7.2 设置 Word 样式

Pandoc 生成 Word 文档时可以指定一个参考样式模板（.dotx 或 .docx）。

1. 创建一个您满意的 Word 文档作为样式模板，命名为 reference.docx。
2. 在 args 中添加：

   "--reference-doc", "C:\\path\\to\\reference.docx"
   

这样生成的文档将使用模板中的样式（字体、标题格式等）。

7.3 批量转换多个文件

您可以修改任务配置，将 ${relativeFile} 改为 ${workspaceFolder}\\*.md，但这样会一次性转换所有 Markdown 文件，可能需要更长的参数。更简单的方法是：使用 VS Code 的“运行任务”时选择不同的文件，或者写一个循环脚本。这里提供一种方式：创建一个新的任务，用 PowerShell 遍历文件夹。

在 tasks.json 中添加另一个任务：

{
    "label": "Convert all MD to Word",
    "type": "shell",
    "command": "powershell",
    "args": [
        "-Command",
        "Get-ChildItem -Filter *.md | ForEach-Object { pandoc $_.Name -o ($_.BaseName + '.docx') --filter C:\\Users\\...\\mermaid-filter.cmd }"
    ],
    "group": "build",
    "presentation": { "reveal": "always" }
}

运行该任务会转换当前目录下所有 .md 文件。

---

8. 备选方案（当 mermaid-filter 无法工作时）

如果您经过多次尝试仍然无法让 mermaid-filter 正常工作（例如网络问题无法下载 Chromium、公司代理限制等），可以使用以下替代方法。

8.1 方案 A：使用 Markdown Preview Enhanced 导出 HTML，再用 Word 打开

步骤：

1. 在 VS Code 中安装 Markdown Preview Enhanced 插件（扩展商店搜索）。
2. 打开您的 Markdown 文件，按 Ctrl+Shift+V 打开预览（注意这是 Markdown Preview Enhanced 的预览）。
3. 在预览窗口中右键 → Export → HTML → 保存为 .html 文件。
4. 用 Microsoft Word 打开该 HTML 文件（Word 能打开 HTML 并保留大部分格式）。
5. 在 Word 中另存为 .docx 格式。

优点：无需安装 Pandoc 和 Node.js，Mermaid 图形在 HTML 中是 SVG 或 Canvas 渲染的，Word 打开后会转为可编辑图形。
缺点：可能出现布局偏移；大型文档转换较慢。

8.2 方案 B：使用 Typora 付费版直接导出 Word

Typora（≥ 1.0 版本，付费）原生支持 Mermaid 渲染，并可直接导出 Word。

1. 在 Typora 中打开 Markdown 文件。
2. 菜单栏 → 文件 → 导出 → Word (.docx)。
3. 完成。

优点：一键操作，无需任何配置，图形完美保留。
缺点：需要购买（约 100 元人民币，一次性买断）。

8.3 方案 C：手动截图插入 Word

如果文档中 Mermaid 图形数量很少（1-3 个），可以：

1. 在 VS Code 中使用 Mermaid 预览插件（如 Markdown Preview Mermaid Support）打开侧边预览。
2. 对每个图形截图（Windows 可使用 Win+Shift+S 截取区域）。
3. 将截图粘贴到 Word 文档中对应位置。
4. 手动调整图片大小。

优点：无需任何额外工具，100% 可控。
缺点：图形多时非常耗时，且图片是位图，缩放可能模糊。

---

9. 常见错误汇总与终极排错指南

错误现象	可能原因	解决步骤
'pandoc' 不是内部或外部命令	Pandoc 未安装或 PATH 未配置	重装 Pandoc 并勾选 PATH；或手动添加 PATH
'node' 不是内部或外部命令	Node.js 未安装或 PATH 未配置	重装 Node.js，重启电脑
'mermaid-filter' 不是内部或外部命令	npm 全局 bin 不在 PATH	使用绝对路径（见 4.2）
Error: Could not find Chromium	puppeteer 下载 Chromium 失败	重新安装 mermaid-filter，换网络或使用淘宝镜像
Parse error on line X	Mermaid 语法错误	检查该行，使用在线编辑器修正
Filter returned error status 1	同上，或 mermaid-filter 内部错误	查看详细错误信息，定位到具体图形
转换成功但 Word 中图形缺失	某些图形渲染超时	增加 mermaid-width 参数，或简化图形
转换后 Word 中文字乱码	字体问题	在参考样式模板中设置中文字体

终极排错流程：

1. 从命令行手动测试：打开命令提示符，cd 到您的 .md 文件所在目录，直接运行：

   pandoc yourfile.md -o output.docx --filter "C:\Users\...\mermaid-filter.cmd"
   

   观察错误信息。如果命令行成功，则 VS Code 任务配置有误；如果命令行失败，则问题在环境或语法。
2. 检查 Mermaid 代码：将每个 Mermaid 代码块单独复制到 https://mermaid.live/ 测试。
3. 更新所有工具：升级 Pandoc、Node.js、mermaid-filter 到最新版。
4. 尝试最小示例：创建一个只包含一个简单 Mermaid 流程图的测试文件，验证工具链是否完整。
5. 查阅日志：mermaid-filter 会在临时目录生成一些中间文件，可设置环境变量 DEBUG=mermaid-filter 获取详细日志。

---

10. 总结与建议

通过本文的详细手顺，您应该能够从零开始搭建一套完整的 Markdown → Word 转换环境，并且顺利处理包含 Mermaid 图形的文档。核心要点回顾：

1. 安装 Pandoc：确保 PATH 正确。
2. 安装 Node.js：获得 npm 环境。
3. 全局安装 mermaid-filter：若命令找不到，使用绝对路径。
4. 配置 VS Code 任务：使用 Ctrl+Shift+B 一键转换。
5. 修复 Mermaid 语法错误：使用引号包裹描述文本，在线验证。
6. 备选方案：当环境搭建困难时，使用 Markdown Preview Enhanced 导出 HTML 或 Typora 付费版。

最佳实践建议：

• 在编写 Mermaid 图形时，养成给所有描述文本加双引号的习惯，能避免大部分语法错误。
• 将 Pandoc 转换任务保存为 VS Code 工作区设置，方便团队共享。
• 对于频繁转换的用户，推荐购买 Typora，节省大量调试时间。

如果您严格按照上述步骤操作后仍遇到未列出的错误，欢迎提供具体的错误截图和 Markdown 片段，以便进一步分析。现在，您可以在 VS Code 中愉快地将带 Mermaid 的文档转换为专业的 Word 报告了！