Mermaid流程图导出到Word：SVG、PNG与清晰度如何选择？

把DeepSeek、豆包生成的Mermaid代码整理进Word时，常见的问题并不只有"能不能生成图片"：浏览器里正常，插入文档后文字却缺失；截图在屏幕上清楚，放大后边缘发虚；流程图看起来完整，却不能单独修改节点。

鲸鱼AI助手涉及AI内容转Word的应用场景，流程图也是这类内容转换需要处理的对象。本文用独立的Mermaid CLI样例讨论图片格式、尺寸和验证方法，不代表产品内部实现，也不是产品效果测评。

1. 先区分三个不同的目标

"流程图成功导出"至少可以指三件事：

目标	应检查什么	不能据此推断什么
图像清晰	在实际插入尺寸下，文字和连线可辨认	不代表其他软件一定显示一致
正常显示	目标编辑器打开、保存、重开后内容完整	不代表节点可以分别编辑
结构可编辑	节点文字、连接线和布局可以继续修改	不是插入一张图片就自动具备的能力

PNG保存的是像素。SVG能够保留矢量图形，但把SVG作为图片插入Word，并不等于把Mermaid源码转换成了一组保留流程关系的Word原生对象。

微软说明，受支持的Microsoft 365应用可以插入和调整SVG图片；实际功能还需要区分应用、平台与版本。不能把这项支持扩展成"所有Word和WPS版本都支持任意SVG内容"。参见微软SVG图片说明。

如果后续需要修改业务流程，应同时保留.mmd源码。修改源码后重新生成图片，是本文示例采用的维护方式。

2. 用同一份源码生成SVG和PNG

本文本机验证使用Mermaid CLI 11.6.0，实际加载的Mermaid依赖为11.8.0。CLI版本和渲染库版本不是同一个概念。这里固定版本是为了交代复现环境，不表示推荐生产环境一直使用这一版本；升级后应重新检查参数和渲染结果。

在独立示例目录中安装依赖：

npm install --save-dev --save-exact @mermaid-js/mermaid-cli@11.6.0 mermaid@11.8.0
npx mmdc --version
npm list mermaid

保留生成的锁文件。CLI需要可用的浏览器运行环境；安装依赖成功，不一定意味着浏览器已经下载完成。基础用法可查阅Mermaid CLI官方仓库。

将以下内容保存为diagram.mmd：

再保存mermaid-config.json：

{
  "theme": "neutral",
  "fontFamily": "Microsoft YaHei, Arial, sans-serif",
  "htmlLabels": false,
  "flowchart": {
    "htmlLabels": false
  }
}

这里同时设置顶层和流程图层的htmlLabels，是针对本次依赖组合的实测结果：只设置流程图层时，节点仍包含HTML标签；只设置顶层时，部分边标签仍包含HTML标签。两处均设为false后，本例输出中未再发现foreignObject元素。这不是其他版本的通用配置要求，也不是Office兼容性保证。当前配置含义可参阅Mermaid的htmlLabels说明，升级后应重新检查输出。

配置字体也不等于安装字体，渲染机器缺少指定字体时仍可能发生替换。

执行：

npx mmdc -i diagram.mmd -o diagram.svg -c mermaid-config.json -b white
npx mmdc -i diagram.mmd -o diagram-1x.png -c mermaid-config.json -b white -s 1
npx mmdc -i diagram.mmd -o diagram-4x.png -c mermaid-config.json -b white -s 4

-s是渲染比例参数，不是"把图片设为300 DPI"的开关。PNG输出有多少像素，应读取实际生成文件，不能只根据参数猜测。

本机首次执行时遇到了Could not find Chrome。本次没有关闭浏览器沙箱，而是通过-p传入以下配置，使用已安装的Edge：

{
  "executablePath": "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
}

保存为puppeteer-config.local.json后，在上面每条渲染命令末尾追加：

-p puppeteer-config.local.json

这是本机实际使用的路径，不是跨平台通用路径。官方允许通过配置指定浏览器，也明确提醒：非配套浏览器的兼容性需要自行验证。参见使用已安装浏览器的说明。

3. 清晰度取决于像素数和插入尺寸

一张PNG是否适合放进Word，不能只看文件大小，也不能只看属性中写着多少DPI。

对于保持纵横比、没有裁切的图片，可以计算：

有效PPI = 图片宽度像素数 ÷ 插入宽度（英寸）
目标像素宽度 = 向上取整（插入宽度厘米数 ÷ 2.54 × 目标PPI）
插入高度 = 插入宽度 × 图片像素高度 ÷ 图片像素宽度

这里讨论的是PPI，即每英寸图像像素数；它与打印机的墨点密度DPI不是同一个概念。本文把300 PPI设为演示用的检查目标，不把它当作所有文档的强制标准，也不认为达到这个数值就一定可读。

本机生成的两张PNG分别为391×592和1564×2368像素。代入不同插入宽度，结果如下：

文件	插入宽度	等比例高度	有效PPI	是否达到示例目标300 PPI
diagram-1x.png	16厘米	24.23厘米	62.1	否
diagram-4x.png	16厘米	24.23厘米	248.3	否
diagram-4x.png	10厘米	15.14厘米	397.3	是

这说明了两个问题。

第一，4倍渲染也不一定够。它是相对于原始渲染尺寸增加像素，不是承诺任何插入尺寸都达到固定密度。

第二，图片没有必要总是铺满正文宽度。本例是纵向图，放到16厘米宽时，高度约24.23厘米。A4纸高29.7厘米，假设上下页边距各2.5厘米，正文高度只有24.7厘米，留给图题、段落间距等内容的空间已经很少。这样的图片即使像素足够，也可能需要缩小或调整版面。

可以用下面的独立Python片段复算，不需要安装第三方库：

from math import ceil

width_px, height_px = 1564, 2368
width_cm = 10
target_ppi = 300

effective_ppi = width_px / (width_cm / 2.54)
required_width_px = ceil(width_cm / 2.54 * target_ppi)
height_cm = width_cm * height_px / width_px

print(f"有效PPI：{effective_ppi:.1f}")
print(f"目标像素宽度：{required_width_px}")
print(f"等比例高度：{height_cm:.2f}厘米")

预期输出为397.3、1182和15.14厘米。实际项目应从图片读取宽高，而不是把本文样例数据当作固定值。PNG的IHDR块记录了像素宽高，可据此进行轻量尺寸检查；仅检查这个头部并不能证明整个PNG文件有效。参见W3C PNG规范。

单纯把文件的分辨率元数据从72改成300，不会凭空增加图像细节。在Word里固定插入宽度后，仍然需要看实际像素数。

4. SVG适合保留矢量，PNG适合做经过验证的回退

格式选择可以从交付要求出发：

• 目标编辑器的SVG显示效果已验证，且需要缩放时保持线条边缘清楚，可以使用SVG。

• SVG在目标环境中出现缺字、标签或样式异常，可以在受控渲染环境中生成PNG，再按实际插入尺寸检查清晰度。

• 交付后需要修改流程逻辑，应保留Mermaid源码；不要把SVG或PNG包装成"可编辑流程图"。

遇到SVG显示异常时，可以检查输出文件中的foreignObject、字体依赖和样式，并比较浏览器与目标编辑器的结果。这是排查方向，不代表出现异常就一定由其中某项造成。

PNG会把渲染时的文字外观固化成像素，但渲染阶段已经缺字时，PNG同样会保留错误。因此，回退前也要检查原始图片。

另外，高像素密度解决不了"节点太多"的问题。把几十个节点压进一页，即使边缘清楚，文字也可能小到难以阅读。此时应拆分主流程和子流程，或考虑横向页面，而不只是继续提高-s。

5. 验证要覆盖最终文档，而不止图片文件

针对本例，可以按下面的顺序验收：

1. 打开生成图片，检查中文、箭头方向、分支标签和内容边界。

2. 插入目标Word版本，保持纵横比，先尝试10厘米宽，检查实际字号是否便于阅读。

3. 保存、关闭并重新打开文档，检查图片是否仍完整，版面是否变化。

4. 如果接收方使用WPS，再在指定版本中单独验证，不用Word的结果代替。

5. 如果最终交付PDF或打印件，还要检查那一份输出，而不是只看编辑窗口。

本次已完成Mermaid CLI 11.6.0渲染、PNG尺寸读取和计算检查，并目视检查了1倍PNG中的中文标签与连线。验证环境为Windows、Node.js 24.15.0及Edge 155.0.4283.62。字体、浏览器和依赖版本变化后，输出尺寸可能不同。

本文尚未完成Word/WPS内的插入、保存重开及打印验证，因此不把上面的建议写成跨编辑器兼容性实测结论。

小结

Mermaid导出到Word，需要分别处理内容正确性、图像质量和页面排版。

SVG保留矢量表示，PNG提供栅格化结果，Mermaid源码负责后续修改。选择格式后，还应根据实际插入尺寸检查像素密度、图高和文字可读性，最后验证接收方真正使用的文档环境。