Markdown 中的 Mermaid 图表：流程图、时序图等

图表比大段文字更能讲清楚流程、架构和时间线。但用图形编辑器画图，意味着要导出图片、把图片和文档存放在一起，而且一有改动就得全部重画。

Mermaid 解决了这个问题：您只需在 Markdown 文件中用几行文本描述图表，预览工具就会把它画出来。图表与文档存放在同一个文件中，会出现在 diff 里，修改起来就像改一句话一样简单。GitHub、GitLab、Obsidian、许多文档生成工具以及 Markdown Preview Editor 都原生支持渲染 Mermaid。

如何添加 Mermaid 图表

创建一个代码块，并将其语言设为 mermaid：

markdown```mermaid
flowchart LR
  A[写作] --> B[预览]
  B --> C{完成？}
  C -- 是 --> D[导出]
  C -- 否 --> A
```

预览工具会把它渲染成：

第一行指定图表类型，之后的内容描述节点和连线。

流程图

流程图是最常用的图表类型。方向写在关键字后面：TD 或 TB（从上到下）、BT、LR（从左到右）或 RL。

mermaidflowchart TD
  start([开始]) --> input[/读取文件/]
  input --> valid{是否有效？}
  valid -- 是 --> save[(保存到数据库)]
  valid -- 否 --> error[显示错误]
  error --> input

标签外面的括号决定了节点的形状：

连线：--> 是箭头，--- 是不带箭头的线，-.-> 是虚线箭头，==> 是粗箭头。用 -- text --> 或 -->|text| 可以添加标签。

用 subgraph 对相关节点进行分组：

mermaidflowchart LR
  subgraph Browser
    editor[编辑器] --> preview[预览]
  end
  preview --> export[HTML / PDF]

时序图

时序图展示参与者之间如何随时间交换消息——非常适合描述 API、身份验证流程和用户旅程。

mermaidsequenceDiagram
  participant U as 用户
  participant A as 应用
  participant S as 服务器
  U->>A: 点击“登录”
  A->>S: POST /login
  S-->>A: 200 OK + token
  A-->>U: 显示仪表盘
  Note over A,S: token 在 1 小时后过期

->> 是实线箭头（请求），-->> 是虚线箭头（响应）。Note over、Note left of 和 Note right of 用于添加注释。使用 loop、alt/else 和 opt 块可以表示循环和分支。

甘特图

甘特图可以把任务列表变成时间线。任务可以从某个日期开始，也可以安排在另一个任务之后（after）。

mermaidgantt
  title 文档冲刺
  dateFormat YYYY-MM-DD
  section 写作
  大纲      :done,   a1, 2026-10-01, 2d
  初稿      :active, a2, after a1, 4d
  section 评审
  同行评审  :        a3, after a2, 3d
  发布      :milestone, after a3, 0d

状态图

状态图描述某个事物如何在不同状态之间转换——比如一个订单、一份文档或一个 UI 组件。

mermaidstateDiagram-v2
  [*] --> Draft
  Draft --> Review : 提交
  Review --> Draft : 要求修改
  Review --> Published : 批准
  Published --> [*]

饼图

想快速展示各部分的占比，可以使用饼图，每个扇区占一行：

mermaidpie title 文档工作的时间都花在哪儿了
  "写作" : 45
  "排版" : 15
  "更新图表" : 40

Mermaid 还支持类图、实体关系图、思维导图、时间线图、Git 图、象限图等。每种图表的语法都可以在 Mermaid 官方网站上查到。

让图表清晰易读的技巧

• 保持精简。 超过 15–20 个节点的图表会变得难以阅读。把它拆成几张图，每张图只表达一个意思。
• 有意识地选择方向。 LR 适合步骤较少的流程；TD 适合层级结构和较长的流程，在窄屏上尤其如此。
• 使用简短的 ID 和易读的标签。 写成 auth[检查会话]，而不是把标签直接当作 ID——这样连线的写法更简短。
• 包含特殊字符的标签要加引号： A["价格：$5（含税）"]。
• 用 %% 添加注释，写在行首。绘图时会忽略这些注释。
• 边写边预览。 少一个箭头或括号就会让整张图表出错，因此实时预览能帮您省去大量猜测。在 Markdown Preview Editor 中，图表会随编辑实时重新渲染，高级编辑器工具栏中的 Mermaid 图表按钮还能插入一个入门模板。

分享带图表的文档

当您将文档导出为 HTML 或 PDF 时，图表会以图片的形式包含在内，读者无需安装 Mermaid。如果想在图表旁边加入公式，请参阅如何在 Markdown 中编写数学公式；至于其他内容——表格、任务列表、提示框——请把 Markdown 语法速查表放在手边。