什么是 Mermaid

Mermaid 是一个「文本转图表」的工具：你按它的语法写一段文本，渲染器就把它画成对应的图。好处很明显：

  • 纯文本：跟 Markdown 一起放在 .md 文件里，用 Git 管版本、diff 都能看清改动；
  • 好改：加一个节点、改一条箭头，就是改一行字，不用重新画图；
  • 不依赖图片文件：不用维护一堆 png，也不会因为换电脑丢图。

GitHub、GitLab 的 README，以及 mdview 都支持渲染 Mermaid。

在 Markdown 里怎么写

把 Mermaid 语法放进一个语言标注为 mermaid 的代码块里就行：

```mermaid
graph LR
  A[开始] --> B{是否登录?}
  B -->|是| C[进入首页]
  B -->|否| D[跳转登录]
```

渲染器看到 ```mermaid 就会把里面的内容当成图表来画，而不是当代码高亮显示。下面分别看几种最常用的图。

流程图 graph / flowchart

流程图用 graph 或 flowchart 开头，紧跟一个方向：TB（从上到下）、LR（从左到右）、RL、BT。然后用「节点 + 箭头」描述流程：

```mermaid
flowchart LR
  A[用户访问] --> B[加载页面]
  B --> C{已登录?}
  C -->|是| D[显示内容]
  C -->|否| E[跳转登录]
  E --> D
```

几个要点：

  • 节点形状用括号决定：A[文字] 是矩形，B{文字} 是菱形（判断），C(文字) 是圆角，D((文字)) 是圆形；
  • 箭头：--> 实心箭头，-.-> 虚线箭头，--- 无箭头连线；
  • 带文字的箭头：A -->|是| B，竖线里写条件。

时序图 sequenceDiagram

时序图用来表示多个对象之间按时间先后的交互，特别适合画接口调用、前后端交互。用 sequenceDiagram 开头：

```mermaid
sequenceDiagram
  participant 用户
  participant 前端
  participant 后端
  用户->>前端: 点击登录
  前端->>后端: POST /login
  后端-->>前端: 返回 token
  前端-->>用户: 进入首页
```

箭头有两种：->> 是实线（请求），-->> 是虚线（返回）。想给某条消息加说明，可以用 Note over 前端,后端: 校验中...。

甘特图 gantt

排项目进度、做计划，甘特图最直观。用 gantt 开头，按「分区 + 任务」组织：

```mermaid
gantt
  title 项目排期
  dateFormat YYYY-MM-DD
  section 设计
    需求评审      :done,    a1, 2026-08-01, 3d
    原型设计      :active,  a2, after a1, 4d
  section 开发
    前端开发      :         b1, after a2, 7d
    后端开发      :         b2, after a2, 7d
    联调测试      :         b3, after b1, 3d
```

关键字：done 已完成、active 进行中、after a1 表示在 a1 完成后开始。3d 表示持续 3 天。

类图等其他图表

Mermaid 还支持类图（classDiagram）、状态图（stateDiagram-v2）、饼图（pie）、ER 图（erDiagram）等。比如一个简单的饼图：

```mermaid
pie title 访问来源占比
  "搜索引擎" : 55
  "直接访问" : 25
  "外链" : 20
```

写法和上面一样——开头声明类型，下面按语法写内容。需要哪种就去查对应语法，思路完全一致。

在 mdview 里看 Mermaid：双击放大

用 mdview 打开带 Mermaid 的 .md 文件，图表会自动渲染。遇到太宽的流程图、时序图，直接双击图表就能进入全屏查看器：滚轮缩放、拖动平移、一键适应窗口，看清细节很方便（这个能力在 v1.0.104 加入，图表配色也换成了清爽的蓝调风格）。

书写建议：Mermaid 对缩进和标点比较敏感，写完一段先用 mdview 渲染确认能画出来，再往下写。节点文字里有特殊符号（括号、问号）时，用引号包起来更稳妥，比如 A["是否OK？"]。

速查小结

要画什么开头写什么典型用途
流程图flowchart LR业务流程、判断分支
时序图sequenceDiagram接口调用、多方交互
甘特图gantt项目排期、任务进度
类图classDiagram类与类的关系
饼图pie占比、构成

记住核心套路：用 ```mermaid 代码块包起来，第一行声明图类型，下面按语法写。剩下的就是记住每种图的几个关键词，需要时查一下即可。