Mermaid 从入门到入土

Mermaid 是一种用文本描述图表的工具。写法接近 Markdown，适合放进文档、博客和知识库里统一维护。和截图式流程图相比，它的优势很直接：可 diff、可复用、可版本化。

这篇文章只保留最常用的部分，目标不是覆盖全部语法，而是让你能尽快开始画图。

Mermaid 适合画什么

• 流程图
• 饼图
• 时序图
• 甘特图
• 类图
• 状态图

如果你的需求是“把思路讲清楚”，Mermaid 往往已经够用。

从一个最小示例开始

graph LR
    A[开始] --> B{是否继续}
    B -- 是 --> C[执行下一步]
    B -- 否 --> D[结束]

graph LR 表示从左到右布局。把方向换成 TB、BT、RL，图的走向也会跟着变。

饼图写法

饼图从 pie 开始。标题可选，数据项使用“名称 + 数值”的结构。

pie
    title 为什么总是宅在家里
    "喜欢宅" : 15
    "天气极端" : 20
    "预算不足" : 65

使用时注意两点：

• 分区名称建议加引号，避免中英文混排时解析歧义。
• 数值会按比例展示，不必手动换算成百分比。

流程图方向

方向声明写在第一行：

• graph TB 或 graph TD：从上到下
• graph BT：从下到上
• graph LR：从左到右
• graph RL：从右到左

方向本身没有绝对优劣，关键看阅读路径。步骤链适合 LR，决策树和审批流通常更适合 TB。

节点形状

Mermaid 支持多种节点外观，常用的有这些：

graph TB
    A[方形]
    B(圆角矩形)
    C((圆形))
    D{菱形判断}
    E[/平行四边形/]

一般建议：

• 普通步骤用方形或圆角矩形
• 判断分支用菱形
• 输入输出场景可以用平行四边形

不要为了“画得花”滥用形状。统一比丰富更重要。

连线样式

最常见的是实线箭头：

graph LR
    A --> B
    B -->|条件满足| C

也可以写成粗线、虚线或无箭头：

graph LR
    A ==> B
    B -.说明.-> C
    C --- D

在文档里表达“依赖”“说明”“可选路径”时，虚线会比普通箭头更清楚。

子图

当流程里存在模块边界时，可以使用 subgraph：

flowchart TB
    subgraph 前端
        A[输入表单] --> B[提交请求]
    end

    subgraph 后端
        C[参数校验] --> D[写入数据库]
    end

    B --> C

这类写法很适合展示系统分层、职责边界和跨模块调用。

写 Mermaid 时的三个建议

1. 先保证信息结构正确，再去微调布局。
2. 单张图不要承载过多分支，复杂流程宁可拆成多张。
3. 统一命名风格，节点文字尽量短，避免出现大段说明。

结语

Mermaid 的学习门槛很低，但真正让图变清楚的不是语法，而是你有没有先把逻辑梳理明白。把它当成一种“可维护的表达方式”，比把它当作“画图软件替代品”更有价值。