1.10 Mermaid

一、Mermaid 是什么

Mermaid 是一种用文本描述图表的工具：通过 flowchart、sequenceDiagram 等关键字，用纯文本定义流程、时序、类结构等图表，再由渲染器生成对应的图形。图表源文件就是普通文本，通常直接写在 Markdown 的代码块里。

正因为图表用文本描述，相比用画图软件（Visio、draw.io）拖拽，它有几个天然优势：

• 纯文本：能写进 Markdown，用 Git 管理版本
• 可维护：改图只需改文本，不用重新截图
• 可搜索：图表内容能被 grep 到
• 便于复用：GitHub、GitLab 与许多文档工具都能渲染常见图表

二、在 Markdown 中使用

把 Mermaid 代码放在 ```mermaid 代码块里即可：

```mermaid
flowchart TD
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作]
    B -->|否| D[结束]
```

效果：

Mermaid 提供二十余种图表类型，常用类型见下表：

上表之外还有需求图（Requirement）、C4 架构图、ZenUML、Sankey、XY 图表、看板（Kanban）等面向特定领域的类型，本文档中较少涉及。下面逐个介绍常用类型。

三、流程图（Flowchart）

流程图是最常用的图表类型，用来表示流程、决策、步骤。

3.1 方向

3.2 节点形状

不同括号表示不同的形状：

3.3 连线

3.4 子图

用 subgraph 把相关节点分组：

四、时序图（Sequence Diagram）

时序图描述多个对象之间的消息交互与先后顺序，适合表达 API 调用、请求-响应流程：

4.1 消息类型

4.2 添加备注

用 Note over 给一段交互添加说明：

五、类图（Class Diagram）

用于描述对象的类结构、字段、方法以及类与类之间的关系：

5.1 关系符号

Mermaid 还提供甘特图、饼图和状态图，分别适合表达计划、占比和状态转换。

六、甘特图（Gantt）

甘特图适合做项目计划、安排时间线：

七、饼图（Pie）

用于展示每个部分在整体中的占比：

八、状态图（State Diagram）

用于描述对象的状态转换，适合表达协议、状态机等：

九、其他图表类型

除了前面介绍的高频类型，Mermaid 还有几类同样会用到的高频图表。

9.1 实体关系图（Entity Relationship，ER 图）

描述实体（如数据库表）以及实体之间的数量关系，数据库课程中常用：

连线两端的符号表示数量约束：|| 表示恰好一个，o{ 表示零个或多个，连起来读作“一个学生可以选择多门课程、一门课程可以被多名学生选择”。实体属性写在花括号内，PK 表示主键。

9.2 Git 图（Git Graph）

用提交、分支与合并直观展示仓库历史，可配合 1.15 版本控制与 Git 一起阅读：

9.3 思维导图（Mindmap）

从中心主题逐层展开，适合梳理知识体系、整理学习笔记：

9.4 时间轴（Timeline）

按时间顺序排列事件，适合课程计划、项目里程碑与个人记录：

上面这些类型已经覆盖日常学习与工作中的绝大多数场景，其余面向特定领域的类型用到时再查阅官方文档即可。掌握常用类型之后，再了解几个实用技巧，会让图表更专业。

十、实用技巧

10.1 节点 ID 与文字分离

节点可以用 id[文字] 的形式定义，后续引用只需写 id，不必重复文字：

flowchart TD
    A[开始] --> B[处理]
    B --> A

10.2 注释

用 %% 写注释，不会渲染到图中：

flowchart TD
    %% 这是注释，不会显示在图中
    A --> B

10.3 样式定制

可以用 classDef 定义样式，再通过 ::: 应用到节点：

flowchart LR
    A:::highlight --> B
    classDef highlight stroke-width:3px

具体颜色要同时检查浅色与深色主题；若发布平台提供主题变量或站点级样式，应优先复用，避免节点说明与背景失去对比度。

10.4 避免图表过于复杂

十一、在线编辑与调试

十二、TODO 清单

• 能根据信息特点选择合适的图表类型（流程、交互、结构、状态、时间、占比等）
• 能写清节点文字与 ID，保持结构清晰
• 能对复杂图表进行拆分、精简，主线依旧清晰
• 能在 AI 辅助下，完成图表的绘制

十三、值得我们思考的问题