Mermaid 实践手册：五分钟上手文本驱动图表渲染

Mermaid 实践手册：五分钟上手文本驱动图表渲染

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid

周五下午的架构评审，你被要求画一张支付调用链图。翻了半小时旧文档，发现图还是上个迭代的样子。Mermaid 解决的就是这类问题：它是用类 Markdown 文本描述图表、再渲染成 SVG 的 JavaScript 工具，图直接放在代码仓库里，改动和 diff 都能走正常的提交流程。

五分钟出图：两步装好 Mermaid

打开终端，先把依赖装进来：

npm install mermaid # 也可以从源码构建 # git clone https://gitcode.com/GitHub_Trending/me/mermaid

再写一个最小页面，保存后用任意静态服务器打开，就能看到流程图：

<pre class="mermaid"> flowchart TD 订单创建 --> 风控校验 风控校验 -->|通过| 生成运单 风控校验 -->|拦截| 人工复核 </pre> <script type="module"> import mermaid from './node_modules/mermaid/dist/mermaid.core.mjs'; mermaid.initialize({ startOnLoad: true }); // 关键项：页面加载后自动渲染 </script>

pre.mermaid里的文本就是图表定义，startOnLoad: true会让它在 DOM 就绪后自动渲染所有带这个 class 的元素。如果页面里只有一张图，这两行就是全部接入成本。

三类常见需求，分开看

先别急着背语法，按"你要解决什么问题"分三组更省事。

理清流程：flowchart

描述审批、工单、状态流转这类"先做什么、后做什么"：

节点形状由括号决定：[]矩形、{}判断、()圆角、[( ]圆柱，基本够用。

描述交互：sequenceDiagram

跨系统调用的顺序、同步还是异步，时序图比流程图更准确：

虚线箭头表示返回消息，loop块表达重试逻辑，这是写接口文档时最常用的两个语法。

呈现结构与计划：ER、类图、甘特图

表结构用 ER 图，对象模型用类图，排期用甘特图。它们语法各自独立，但写法风格一致：第一行声明图类型，后面逐行写定义。

速查一下最常用的几种：

把 Mermaid 接进自己的项目

前端框架里用 render API

React、Vue 这类场景一般不靠startOnLoad，而是手动渲染。官方推荐 v10 起的mermaid.render：

import mermaid from 'mermaid'; mermaid.initialize({ startOnLoad: false }); // 关掉自动渲染，自己控制时机 const { svg } = await mermaid.render('订单流程图', 编辑器里的文本); container.innerHTML = svg;

预期效果：编辑器内容一变，就重新调用一次，图跟着更新。

Markdown 文档站里直接写

大多数静态文档站（VitePress、Docusaurus 等）都有 mermaid 插件，开好后在 Markdown 里直接嵌围栏代码块：

![mermaid](https://web-api.gitcode.com/mermaid/svg/eNpLT8wrKeFSUCjJLMlJVXg2Zf2T3TOeTdn5smHBy_ae5yu6ny-aCJQtTk0uyczPU3iyo-HZnPlAgafrd77YsuzF9onPOncqWKXk56XqKJQY6igYGRiZ6BoY6xoA2YYGKQC0Sip4)

保存后刷新页面，围栏代码块就地渲染成图，无需任何额外配置。

CI 里批量导出图片

要给 PPT、邮件、Wiki 用 PNG 时，用官方 CLI 包导出：

npx @mermaid-js/mermaid-cli -i 订单流程.mmd -o 订单流程.svg # 需要高清位图时追加 --scale 2

放进发布流水线，图表和代码一起构建、一起更新，评审 PPT 里的图永远不会是上个版本的。

常用配置速查：

避坑清单：新手最常碰的五件事

渲染出来是空白，控制台有报错。根因：定义文本里有语法错误，报错会带出行号。 解法：按行号修文本；大段定义可以先丢进官方 Live Editor 验证再粘回项目。

节点文字溢出边框、被裁掉。根因：SVG 默认按容器宽度缩放，宽图被压扁。 解法：flowchart.useMaxWidth: false，让图按内容撑开。

点击跳转不生效，怀疑版本问题。根因：默认securityLevel是 strict，点击、脚本类交互被拦。 解法：确认是内部可信内容后改为loose，并在代码里注释说明理由。

同页多张图，ID 冲突或样式串台。根因：多个图共用自动生成的标记 ID。 解法：开启deterministicIds: true，必要时配deterministicIDSeed固定布局。

中文显示成方框或衬线字体。根因：默认字体栈对中文支持有限。 解法：fontFamily指定'PingFang SC', 'Microsoft YaHei', sans-serif这类栈。

几个进阶用法，一句话说明适用条件：

• 图超过 15 个节点时，用subgraph分层，比继续加连线可读得多。
• 全公司统一视觉时，用themeVariables覆写主色，别每个图单独调。
• 需要给设计稿交付精确尺寸时，用 CLI 的--scale而不是浏览器截图。
• 追求 CI 截图稳定时，deterministicIds加固定 seed，布局才可复现。

评审那天，你不再翻旧文档了——直接把.mmd文件推到仓库，流水线里导出最新的 SVG 贴上 PPT。它适合把图当代码管的团队；如果你需要的是像素级自由排版，文本语法反而不如专业绘图工具顺手。

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid