从零到完美：Mermaid 时序图绘制工作流

2026-06-05T02:00:00.000Z

写在前面

最近在写一份技术文档，需要画架构图、时序图、流程图，加起来十几张。我比较抗拒用鼠标拖框——改个文字要重新对齐，换个节点要重画连线。

Mermaid 用代码生成图就好多了，改文字就改图。但问题来了：AI 生成的 Mermaid 代码渲染出来的 SVG，浏览器看着挺好，一插进 Word 就炸了。

矩形变黑块。线条消失。箭头方向乱跑。

花了一整天踩坑，最后把 beautiful-mermaid 这个开源库从里到外改了一遍，打包成了一个换台设备也能一键跑的工具包。这篇文章就是踩坑记录。

TIP: 如果你只是想在 Word 里插一张 Mermaid 图，直接跳到最后一节看工具包用法。

先看效果

这是同样的 Mermaid 源码，经过工具包渲染后的输出，直接拖进 Word 完美显示：

IMPORTANT: 问题不在 Mermaid，也不在 beautiful-mermaid。问题在 Word 的 SVG 渲染能力——它不支持 CSS 变量 var(--bg)，不支持 color-mix()，也不认 orient="auto-start-reverse"。

第一关：文字全溢出了

刚开始渲染的第一批图，所有中文标签都溢出边框。

追了一下源码，beautiful-mermaid 估算文字宽度用的公式是 text.length × fontSize × 0.52。这个 0.52 是拉丁字符的平均宽高比。中文字符的宽高比接近 0.92——差了一倍。一个 5 字中文标签，估算宽度 34px，实际需要 60px。

修起来简单：数一下中文字符数，分别乘不同的系数。

// 原来：所有字符按拉丁算
return text.length * fontSize * widthRatio;

// 改后：中文单独算
const cjk = (text.match(/[一-鿿]/g) || []).length;
const latin = text.length - cjk;
return latin * fontSize * widthRatio + cjk * fontSize * 0.92;

修完这个，文字不溢出了。但图还是不对。

第二关：菱形又大又丑

流程图里的判断节点（菱形）用的是 side = max(width, height) + diamondExtra。原库的 diamondExtra: 24——额外加 24px。一个"资源负载评估"标签，文字宽 60px，加上 32px 内边距，再加上 24px 额外空间，菱形撑到 116×116。

旁边的矩形节点"接收任务"才 80×38。菱形比矩形大三倍，视觉上很突兀。

两刀修：diamondExtra 砍到 8，长标签加换行。"任务复杂度
评估"拆成两行后，菱形从 118px 缩到 100px。

但在 beautiful-mermaid 里默认不生效——escapeXml 会把 < 转成 <。得让 escapeXml 保留，然后把单行改成多行。

第三关：时序图缺胳膊少腿

Mermaid 的标准时序图有几个要素：参与者矩形、虚线生命线、激活框（覆盖在生命线上的细条）、箭头、文字。

beautiful-mermaid 只渲染了前两个+后两个。激活框没了。

原因是激活框只在 Mermaid 源码里显式标了 +/- 时才画。标准 Mermaid 不需要——自动从第一条消息到最后一条画激活框。

补了一段自动计算逻辑：每个参与者扫描自己的第一条和最后一条消息，中间全画激活框。白底、黑边框、居中在虚线上。

然后是箭头起止点。原版箭头从参与者中心出发，直接越过激活框到目标中心——箭头扎进框里了。改成从激活框右边缘出发，到目标激活框左边缘止。

自调用消息（自己发给自己的箭头）的箭头是折线，向右绕一圈回来。这个折线把激活框也带歪了——alt 框的宽度只算了参与者的宽度，没算自调用消息向右延伸的部分。修复方式是在框宽度计算里扫描框内每一条消息的标签位置。

第四关：Word 不认你的 CSS

前三关调完之后，浏览器里看着已经很好了。插进 Word——全崩。

F12 看了一下 SVG 源码，beautiful-mermaid 用 CSS 变量实现主题：

--_node-fill 的定义在