#Mermaid（画图的引擎）

#这是什么

上面那些图都是它画的。Mermaid 是一个用文字描述图形的工具，本版本是 Pamphlet 唯一实现了的引擎。

一个围栏语言 mermaid，第一行的关键字决定画哪种图。

#先装一次

npm i -g mermaid-isomorphic playwright && npx playwright install chromium

首次约 150MB、约 1 分钟。装完跑 pamphlet doctor 确认：

✓ mermaid（mermaid）

#为什么要下一个浏览器

因为 Mermaid 必须用真实浏览器的布局引擎算文字尺寸。

jsdom（一个纯 JavaScript 的假浏览器）没有实现 SVGTextElement.getBBox()——量不出一段文字有多宽，就没法为图形排版。

这不是选型偏好。Mermaid 组织成员 @aloisklink 明确否定过 jsdom 方案：https://github.com/mermaid-js/mermaid/issues/3886#issuecomment-1341694822

代价落在「装一次」而不是「每次用」。

#浏览器是惰性启动的

纯文字文档永远不会拉起它。 只有真的遇到 ```mermaid 围栏才启动。

DIAG-303 的超时门槛是 10 秒，约是最坏值的 13 倍。

#它能画哪些图

十三种。每一种都有两页：一页讲 Pamphlet 自己的写法，一页讲这里的 Mermaid 围栏写法，画出来是同一张图。

#画得出来但有瑕疵的

timeline / quadrantChart / journey / packet-beta / radar-beta / xychart-beta 能画，但有几处颜色不跟主题走，会报 DIAG-304。原因是那几种图的配色由引擎从主色算出来，算完的值既不是我们喂进去的哨兵、又躲过了替换。

#有两处颜色它自己写死了（已知不跟主题）

状态图的连线标签色（red）和甘特图分隔线（navy）写死在 Mermaid 各图种的样式表里，换不成主题变量，每次编译会报两条 DIAG-304。

这两处是已知不跟主题的：仓库自己的 examples/demo.md 编译时也会报这两条，那不是 demo 写错了。

留着它们报出来而不是在别名表里认领掉，是因为这两条是真警告不是误报——暗色主题下那条 navy 的竖线几乎看不见。将来 Mermaid 改了默认样式，我们也能第一时间知道。

#不认中文的两种

sankey-beta（桑基图）和 requirementDiagram（需求图）的解析器只认 ASCII 标识符，中文节点名直接报 DIAG-303。实测于 mermaid 11.17.2。

要画流量分配，用流程图把数值写在连线标签上。

#图源写错了怎么办

得到 DIAG-303，提示会建议把图源贴到 https://mermaid.live 上定位——那是 Mermaid 官方的在线编辑器，报错比命令行清楚。

图画不出来时产物照样写出来：那张图的位置留一个占位框写明原因，其余部分完全正常，退出码是 1。

#CI 里要多做一步

镜像里得装 Chromium 及其系统依赖：

npx playwright install --with-deps chromium

完整的 CI 配置见在 CI 里检查文档。

出处：ADR-0004