问题描述：

VS Code 中将含 Mermaid 图形的 Markdown 文档转换为 Word（macOS 版）

概述

通过 Pandoc + mermaid-filter 实现 Mermaid 代码块自动渲染为图片并嵌入 Word 文档。

---

第一步：安装 Pandoc

方法一：Homebrew（推荐）

brew install pandoc

方法二：安装包

1. 访问 Pandoc - Installing pandoc
2. 下载 macOS 安装包（.pkg 文件）
3. 运行安装包完成安装

验证安装

pandoc --version

---

第二步：安装 Node.js 与 npm

方法一：Homebrew

brew install node

方法二：安装包

1. 访问 https://nodejs.org/ 下载 LTS 版本
2. 运行安装包完成安装

验证安装

node --version npm --version

配置国内镜像（可选）

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

---

第三步：全局安装 mermaid-filter

npm install -g mermaid-filter

验证安装

mermaid-filter --help

查找安装路径

npm config get prefix

输出通常为：/Users/你的用户名/.npm-global

你的 mermaid-filter 完整路径：

/Users/你的用户名/.npm-global/lib/node_modules/mermaid-filter/index.js

---

第四步：配置 VS Code 一键转换任务

打开命令面板

按 Cmd + Shift + P，输入 Tasks: Configure Task，选择 Others

配置 tasks.json

在 .vscode/tasks.json 中写入以下内容：

{ "version": "2.0.0", "tasks": [ { "label": "Convert MD to Word with Mermaid", "type": "shell", "command": "pandoc", "args": [ "${relativeFile}", "-o", "${relativeFileDirname}/${fileBasenameNoExtension}.docx", "--filter", "/Users/你的用户名/.npm-global/lib/node_modules/mermaid-filter/index.js" ], "group": { "kind": "build", "isDefault": true }, "presentation": { "reveal": "always", "panel": "shared", "clear": true }, "problemMatcher": [] } ] }

运行转换

打开一个含 Mermaid 图的 .md 文件，按 Cmd + Shift + B 即可转换为 Word。

转换后的 .docx 文件会生成在同目录下。
效果截图
PixPin_2026-04-08_20-55-102940×1660 510 KB

---

第五步：Mermaid 语法常见错误

错误写法	正确写法
S: 状态: 描述	S: "状态: 描述"
A[你好！]	A["你好！"]
A->B: 消息"hello"	A->B: "消息\"hello\""

建议使用 https://mermaid.live/ 在线验证 Mermaid 代码。

---

第六步：进阶配置

调整图片宽度

在 args 中添加：

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

使用 Word 样式模板

"--reference-doc", "/path/to/reference.docx"

批量转换

for file in *.md; do pandoc "$file" -o "${file%.md}.docx" --filter /Users/xingranya/.npm-global/lib/node_modules/mermaid-filter/index.js done

---

常见错误排查

错误信息	解决方案
pandoc: command not found	重新安装 Pandoc 并重启终端
mermaid-filter: command not found	使用绝对路径替代命令名
Parse error on line X	Mermaid 语法错误，用 https://mermaid.live/ 修正

---

备选方案

1. Markdown Preview Enhanced：导出 HTML 后用 Word 打开
2. Typora 付费版：直接导出 Word
3. 手动截图：截图后插入 Word

网友解答：

---

--【壹】--：

佬友这个不错诶,比我之前找的这个https://mermaid.ai/方便多了

---

--【贰】--： 星苒鸭:

mermaid-filter

太救命了. 正好需要, 省去了大量的时间. 要不实在是太麻烦了. word这种东西又卡又慢但有时候又必须得用.

---

--【叁】--： 星苒鸭:

手动截图：截图后插入 Word

说到截图，顺便推一下这个工作：https://mermaid-exporter.pages.dev
在线渲染、快捷导出/复制，比截图分辨率友好一点