技术文档、学术论文或 AI 对话记录中，Mermaid 流程图和 LaTeX 数学公式几乎成了“半标准”写法。但大多数人的最终交付物是 Word（.docx），而 Word 原生既不认识 Mermaid，也不理解 LaTeX。于是，截图、粘贴、调格式的机械劳动反复上演。
其实，围绕“从 Mermaid/LaTeX 到 Word”这个需求，已经衍生出多种技术实现路径。本文将从原理到实践，介绍几种可落地的方案，并深入探讨其中的技术细节与取舍。
一、技术背景：为什么 Word 不能直接显示 Mermaid 和 LaTeX？
Word 内部使用 Office Open XML 格式存储内容。图表通常以图片（EMF/PNG）或矢量绘图对象（如 DrawingML）存在。而 Mermaid 是基于 JavaScript + SVG 渲染的声明式图表，必须经过渲染引擎转换为图像或矢量描述才能嵌入。
LaTeX 公式在 Word 中则有两种可接受的形式：
- OMML（Office Math Markup Language）：Word 原生数学格式，可通过插入公式对象输入。
- MathML：一种 XML 标准，Word 2019 及以上版本支持导入。
因此，任何转换工具的核心任务就是：将 Mermaid 代码 → 图片/矢量图，将 LaTeX → OMML 或 MathML。
二、本地命令行方案（适合开发者，完全可控）
2.1 Mermaid 渲染：使用 @mermaid-js/mermaid-cli
Mermaid 官方 CLI 工具 mmdc 基于 Puppeteer，调用无头 Chromium 渲染 SVG，再转换为 PNG/PDF。
bash
npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.png -t forest -b transparent -w 800
参数说明：
-t主题（default/forest/dark/neutral）-b背景色（transparent/white）-w输出宽度（保持比例）--scale缩放因子（提高分辨率）
批量处理脚本（Bash）：
bash
for file in *.mmd; do
mmdc -i "$file" -o "${file%.mmd}.png" -w 1200 --scale 2
done
2.2 LaTeX 公式转换：pandoc + latex2mathml 或 tex2oMML
Pandoc 可以将 LaTeX 公式转为 OMML 直接写入 .docx，无需中间图片。
bash
pandoc input.md -o output.docx --mathml
但注意：--mathml 生成的是 MathML，Word 打开时可能会降级为图片或显示异常。更好的方式是使用 --mathjax 或自定义 writer 生成 OMML。一个更稳妥的组合是：
bash
pandoc input.md -o output.docx --from markdown+tex_math_dollars --to docx --mathml
如果希望将 LaTeX 独立片段（不包含在 Markdown 中）直接转换为 Word 公式，可以使用 Python 库 latex2mathml 生成 MathML，再用 python-docx 插入。
三、Pandoc + 过滤器方案（适合批处理与 CI/CD）
Pandoc 的核心优势在于过滤器机制。我们可以编写一个 Lua 或 Python 过滤器，在转换过程中实时拦截 Mermaid 代码块，调用渲染引擎生成图片，并将图片嵌入文档。
3.1 使用 pandoc-mermaid-filter
安装（Node.js 环境）：
bash
npm install -g pandoc-mermaid-filter
使用命令：
bash
pandoc doc.md -o doc.docx --filter pandoc-mermaid-filter
过滤器内部流程：
- 解析 Markdown AST，找到类型为
CodeBlock且语言为mermaid的块。 - 调用
mmdc或mermaid浏览器渲染，生成临时图片。 - 将代码块替换为
Image元素（包含 base64 或相对路径）。 - 最后 Pandoc 正常生成
.docx。
3.2 自定义 Lua 过滤器（更轻量）
如果你不想安装 Node.js，可以写一个简单的 Lua 过滤器，利用外部 mmdc 命令：
lua
function CodeBlock(el)
if el.classes:includes("mermaid") then
local filename = os.tmpname() .. ".png"
local cmd = "mmdc -i /dev/stdin -o " .. filename
local f = io.popen(cmd, "w")
f:write(el.text)
f:close()
return pandoc.Image({}, filename)
end
end
这个过滤器会为每个 Mermaid 代码块生成 PNG 并嵌入。注意清理临时文件。
3.3 处理 LaTeX 公式的进阶技巧
Pandoc 默认会把 $...$ 和 $$...$$ 转成 OMML，但某些宏包（如 \begin{align*}）可能不支持。可以使用 --webtex 将公式转为 SVG 图片，但会丢失可编辑性。技术报告通常建议保留 OMML，放弃极少用到的复杂宏包。
四、在线转换服务的技术原理
如果你不想安装任何工具，也可以使用在线转换服务，以 AI转换助手 为例，在线服务的工作流程大致如下：
- 前端：提供一个文本输入框，接收多段 Mermaid 代码和 LaTeX 公式。
- 后端渲染：
- Mermaid：使用
mermaid库 +puppeteer（或playwright）渲染 SVG，再通过sharp或ImageMagick转换为 PNG。 - LaTeX：使用
MathJax-node或latexml将 LaTeX 转为 MathML。
- 文档组装：使用
docx（JavaScript）或python-docx创建.docx文件，按顺序插入图片和公式对象。 - 性能优化：对批量图表使用队列渲染，避免同时启动过多 Puppeteer 实例导致内存爆炸。
这种方案的优点是零配置，但缺点是需要信任第三方服务器，且对超大图表（超过 5000 节点）可能超时。
五、深入技术细节：如何保证公式与图表的保真度？
5.1 Mermaid 图表的清晰度
- 矢量 vs 位图：Word 中插入 SVG 可以无限缩放，但部分旧版 Word 对 SVG 支持不佳。插入 PNG 更通用，但需设置足够 DPI（建议 300 DPI 以上）。
- 字体嵌入：Mermaid 默认字体是
trebuchet ms，在 Linux 服务器上可能缺失，导致渲染文本偏移。解决方案：在mmdc中指定--cssFile或使用系统通用字体（Arial）。
5.2 LaTeX 公式的边界情况
- 矩阵、多行公式：
amsmath环境（align*,gather*）需要转换为 MathML 的<mtable>结构。MathJax 渲染效果最好，但输出 MathML 后 Word 可能丢失对齐。替代方案：将复杂公式渲染为 SVG 图片，放弃可编辑性，换取绝对保真。 - 特殊符号：
\mathbb,\mathcal需要 Unicode 映射，某些字体在 Word 中可能缺失，建议使用 Cambria Math 字体。
六、实践建议与工作流选择
| 场景 | 推荐方案 | 技术准备 |
| 个人偶尔转换，图表<10张 | 在线服务（注意隐私） | 无需安装 |
| 开发者本地批量处理 | Pandoc + pandoc-mermaid-filter |
Node.js + Pandoc |
| 团队 CI/CD 自动生成文档 | Docker 镜像封装 Pandoc + mmdc | 构建镜像 |
| 极度复杂的公式（如量子力学符号） | 转 SVG 图片嵌入 | pandoc --webtex 或 tex2svg |
示例：一条完整的 Docker 转换命令
dockerfile
FROM pandoc/latex:latest
RUN apk add --no-cache nodejs npm chromium
RUN npm install -g @mermaid-js/mermaid-cli pandoc-mermaid-filter
ENTRYPOINT ["pandoc", "--filter", "pandoc-mermaid-filter"]
使用：
bash
docker run --rm -v $(pwd):/data pandoc-mermaid /data/doc.md -o /data/doc.docx
七、总结与展望
从 Mermaid 和 LaTeX 到 Word，本质上是一个“声明式内容”到“排版化文档”的编译过程。随着文档构建系统（如 mdbook、Quarto）的发展，未来可能直接输出原生 Word 支持的结构化数据。但目前，掌握上述几种技术方案，足以让大多数人摆脱手动截图的低效循环。
