Mermaid 11.17：用文本画图，文档与代码同步的实用方案

它解决的是文档腐烂问题

Mermaid 的核心定位不是画图工具，而是解决文档跟不上代码的问题。README 里明确说，它的主要目的是帮助文档赶上开发进度。传统做法是用 Visio 或 draw.io 画图，然后导出图片放进文档。图一旦改了，图片要重新导出，文档经常因此过期。Mermaid 把图表定义写成文本，和代码一样存放在仓库里。修改图表就是改一段文本，提交后渲染结果随之更新。这个机制让图表和代码能一起走版本控制，文档腐烂的速度被明显减缓。适合的人群包括：维护 API 文档的工程师、写架构说明的后端团队、以及需要把流程固化到 README 里的开源项目维护者。

文本到图表的实际流程

Mermaid 的工作方式分两步：先用 Markdown 风格的文本定义图表，再通过渲染器生成图形。文本定义类似代码块，比如流程图用 graph TD 开头，然后写节点和连线。渲染器在浏览器中解析这段文本，转换成 SVG 或 Canvas。整个过程不需要外部服务，纯 JavaScript 实现。README 提到它可以用在生产脚本里，这意味着图表定义可以作为数据流的一部分。比如在 CI 中，用 Mermaid 生成架构图并嵌入构建产物。文档还提到，它可以和 GitHub 等平台集成，GitHub 在 2022 年就支持在 Markdown 文件中直接渲染 Mermaid 图。这个机制的关键点是：图表是活的数据，而不是静态图片。

从安装到第一张图的真实命令

上手的路径很直接。README 指向了 Live Editor 和文档站，但实际安装是通过 npm。在项目里运行 npm install mermaid，然后引入模块。一个最小示例：在 HTML 中加载 mermaid 包，调用 mermaid.initialize 和 mermaid.run，页面里包含的 mermaid 代码块就会被渲染成图。文档中给出的典型写法是，用 <pre class="mermaid"> 包裹图表定义，Mermaid 会自动扫描并替换。如果你用 GitHub，直接在 Markdown 文件中写 ```mermaid 代码块即可，无需任何本地安装。CDN 方式也支持，jsDelivr 上有官方包。配置方面，mermaid.initialize 接受一个对象，可以设置主题、安全级别等。这些命令和配置键在文档的 Usage 和 Config 部分有详细说明，但 README 本身没有给出具体示例，实际使用时需要查阅文档。

安全模式与渲染限制

Mermaid 的渲染器在浏览器中执行，因此安全性是设计中的一环。README 专门列了 Security and safe diagrams 一节，说明它默认有安全机制。具体来说，渲染时可能禁用某些功能，比如点击事件或外部链接，以防止 XSS 攻击。这个安全级别可以通过配置调整，但默认是保守的。这意味着，如果你需要交互式图表，比如点击节点跳转，可能需要修改配置，但会降低安全性。另一个限制是布局控制。Mermaid 自动计算节点位置，用户无法手动拖拽调整。对于简单流程图这没问题，但复杂图表可能布局混乱，且无法微调。文档没有提供手动布局的选项，这是它的设计取舍。如果你需要精确控制每个节点的坐标，Mermaid 不是合适的工具。

替代方案：Graphviz 与 PlantUML 的差异

和 Mermaid 最接近的替代品是 PlantUML 和 Graphviz。PlantUML 同样用文本定义图表，但它的语法更接近 UML 标准，支持时序图、用例图等，渲染依赖 Java 环境。Graphviz 则用 DOT 语言描述图结构，布局算法更强大，适合有向图和无向图，但语法更底层，学习曲线陡。Mermaid 的差异在于：它专为 Markdown 生态设计，语法更接近自然语言，比如 graph TD 比 DOT 的 digraph G {} 更直观。而且 Mermaid 是纯 JavaScript，可以直接嵌入浏览器和 Node.js 项目，不需要额外运行时。Graphviz 的布局质量通常更好，但集成成本高。PlantUML 在 UML 建模上更专业，但需要服务器或本地 Java。选择哪个取决于你的主要场景：如果是在 GitHub 上写文档，Mermaid 最顺手；如果需要复杂布局或 UML 标准图，Graphviz 或 PlantUML 更合适。

维护成本与许可证考量

Mermaid 的许可证是 MIT，这意味着你可以自由使用、修改和分发，包括商用。没有 Copyleft 义务，闭源项目也能集成。维护成本方面，Mermaid 的版本迭代较快，最近一次发布是 11.17.2，两天内连续发布了三个补丁版本。这说明项目活跃，但也意味着 API 可能有变动。升级时需要关注 changelog，特别是配置项和渲染行为的变化。项目使用视觉回归测试来保证渲染质量，README 提到依赖 Applitools 和 Argos 进行 PR 审查，这降低了升级导致图表变形的风险，但不等于零。团队在采用前应固定版本，避免自动升级带来的意外。另外，Mermaid 的依赖包体积不小，如果用在网页中，需要考虑加载性能。bundlephobia 链接在 README 中，但具体体积数据需要自行查看。

编辑结论

Mermaid 适合那些文档经常过期、希望把图表放进版本控制里的团队，尤其是已经在用 GitHub 或 Markdown 的工程。非程序员可以用 Live Editor 快速画图，开发人员则可以将图表定义嵌入 CI 脚本，让文档随代码更新。但它不适合需要精细控制布局或复杂交互的专业绘图场景，也不适合对渲染结果有严格像素要求的团队。采用前先验证两件事：一是你需要的图表类型（如流程图、时序图、甘特图）在 Mermaid 中是否成熟，二是你使用的平台（GitHub、GitLab、Notion 等）对 Mermaid 的原生支持或渲染插件是否可用。若这两点满足，Mermaid 能直接减少文档维护成本；若不满足，你可能会在调试语法和渲染差异上花掉省下的时间。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes