Cursor blinking
Blog

Mermaid 使用简明教程：把图写进文档，而不是把文档画成截图

教程|mermaid|字数 4,883|阅读时长 ≈ 13 分钟

更新时间：2026-07-09

这是一篇给 Mermaid 新手和文档常写者准备的简明教程。它不要求你先懂 UML，不要求你有绘图软件会员，也不要求你为了画一张流程图先修炼成架构图大师。

目标很朴素：让你从第一张能跑的图开始，逐步学会流程图、时序图、状态图、ER 图、计划图和 Git 图，最后知道怎么把 Mermaid 放进真实文档流程里。

先说结论：Mermaid 不是在线版 Visio，也不是给文档加点装饰。它更像 Markdown 里的画图语法：你写一段文本，平台把它渲染成图。文本能复制、能搜索、能 review、能进 Git；图也就不再是那种“看起来很正式，但没人知道源文件在哪里”的遗迹。

你写的是代码，看到的是图。图跟着文档一起维护，改动能被审查，过期也更容易修。以后再遇到流程变化，不用围着一张旧截图猜“当年这里到底想表达什么”。

这篇适合谁

  • 你经常写 README、方案文档、接口说明、PR 描述或复盘文档。
  • 你想让流程图、时序图、状态图、ER 图和计划图能跟着文本一起维护。
  • 你不想为了画一张小图打开一个大型绘图软件，然后被工具栏教育人生。
  • 你希望 AI 或同事生成的图能被审查、修改和复用，而不是变成一张无法编辑的图片。

如果你只是偶尔画一张会议白板图，也能看；但这篇的重点是：如何把 Mermaid 用进真实文档流程。

先记住一句话

Mermaid 的核心就三步：

  1. 声明你要画什么图。
  2. 写清楚有哪些东西，以及它们之间是什么关系。
  3. 放进 mermaid 代码块里，让支持 Mermaid 的平台渲染。

最小例子长这样：

Codemarkdown
```mermaidflowchart LR  A[需求] --> B[实现]  B --> C[验证]```

翻译成人话就是：

  • flowchart LR：我要画流程图，方向从左到右。
  • A[需求]：节点 ID 是 A，显示文字是“需求”。
  • -->：画一条箭头。
  • B --> C：从“实现”走到“验证”。

这就是 Mermaid 的第一口饭。先别急着加主题、图标和复杂布局。刚开始最该关心的不是颜色和边框，而是你下次打开文档时，能不能立刻看懂“事情怎么流动”。

第一层：先跑通第一张图

如果你从来没写过 Mermaid，先按这个顺序走。不要跳。跳步骤这种事通常发生在“我就改一行配置”的前五分钟。

  1. 打开一个支持 Mermaid 的 Markdown 环境，比如 GitHub、GitLab、部分文档站、Obsidian、Notion 插件环境，或者 Mermaid Live Editor。
  2. 复制下面这段代码。
  3. 看它是否能渲染成图。
  4. 改一个节点文字，再看图是否跟着变。
Codemermaid
flowchart LR  idea[想法] --> draft[草稿]  draft --> review[评审]  review --> publish[发布]

如果能显示，恭喜，你已经越过了 Mermaid 最重要的门槛：它不是靠鼠标拖来拖去，而是靠文本描述关系。

如果不能显示，先别怀疑自己。常见原因是：

  • 当前平台不支持 Mermaid。
  • 代码块语言不是 mermaid。
  • 平台支持的 Mermaid 版本较旧。
  • 复制时多了奇怪空格、少了反引号，或者把外层 Markdown 代码块也一起复制进去了。

Mermaid 的快乐很朴素：代码对了，它就画；代码错了，它会用一种很像谜语的方式提醒你。

第二层：看懂基础语法

Mermaid 初学者最容易被各种括号吓住。其实先记住常用的几个就够。

Codemermaid
flowchart TD  start([开始])  step[普通步骤]  decision{判断条件}  database[(数据库)]  finish([完成])   start --> step  step --> decision  decision -->|是| database  decision -->|否| finish  database --> finish

上面这张图包含了入门最常用的语法：

写法常见含义
A[文本]普通矩形节点
A(文本)圆角节点
A{文本}判断节点
A[(文本)]数据库或存储
A --> B普通箭头
`A --> | 说明 | B`带说明的箭头
flowchart TD从上到下
flowchart LR从左到右

节点 ID 和显示文字可以分开：

Codemermaid
flowchart LR  userInput[用户输入一段很长但仍然需要显示的文案]  api[API 校验]  userInput --> api

这里的 userInput 和 api 是给 Mermaid 看的稳定 ID，“用户输入一段很长但仍然需要显示的文案”和 API 校验 是给人看的文字。ID 建议用英文，显示文字可以用中文。这样后面连线更清楚，不会在一堆中文节点名里绕晕。

你可以把 Mermaid 语法理解成“点名 + 连线”：

  • 先给东西起名。
  • 再说明它们怎么连接。
  • 最后补一点方向、标签和分组。

这就够你画出 60% 的日常文档图了。剩下 40% 是慢慢发现“原来这个坑我也会踩”。

第三层：先选对图，再判断该不该画

Mermaid 是一个基于 JavaScript 的图表工具，用类似 Markdown 的文本定义生成图形。官方文档把 Mermaid 分成三件事：部署、语法和配置。普通写作者最先要学的是语法；平台或网站维护者才需要深入部署和全局配置。

Mermaid 支持很多图形。刚开始别贪多，先记住这些常用选择：

你想表达优先用典型开头
步骤、分支、模块关系流程图flowchart TD
谁先调用谁、谁返回什么时序图sequenceDiagram
一个对象有哪些状态、怎么切换状态图stateDiagram-v2
实体、表、领域对象之间的关系ER 图erDiagram
项目排期和阶段计划甘特图gantt
分支、提交、合并策略Git 图gitGraph
层级脑图Mindmapmindmap
时间事件列表Timelinetimeline
粗略比例Piepie

判断方式可以更直接：

  • 你在说“先做 A，再做 B，遇到 C 怎么办”：用流程图。
  • 你在说“浏览器调用 API，API 调数据库，再返回”：用时序图。
  • 你在说“草稿、审核中、已发布、已归档之间怎么流转”：用状态图。
  • 你在说“作者、文章、评论、分类之间怎么关联”：用 ER 图。
  • 你在说“一周做什么，哪天完成”：用甘特图或时间线。

Mermaid 很适合放进 README、方案文档、接口说明和复盘文档里，用来解释流程、调用、状态、数据关系和计划。它不太适合做像素级 UI 设计稿、复杂统计图表，或者那种试图解释整个系统、所有边界、全部历史包袱和未来三年规划的巨型大图。

Mermaid 最好的使用姿势是：一张图只解释一个问题。如果你发现自己正在把第 35 个节点塞进图里，先停一下。不是 Mermaid 不努力，是这张图可能已经从“帮助理解”变成“下周的你也不想重读”了。

选错图会让语法变别扭。别用流程图硬画状态机，也别用时序图硬画组织结构。工具没有错，只是我们有时会忍不住拿一把螺丝刀去煮面。

第四层：用流程图讲清步骤和分支

流程图是 Mermaid 最常用的入口。它用节点和边表达“事情怎么走”。

Codemermaid
flowchart LR  input[输入] --> validate{校验通过?}  validate -->|是| save[(保存)]  validate -.->|否| error[显示错误]  save ==> done([完成])

这里有几件事值得记：

  • flowchart 和 graph 都可以声明流程图，日常建议统一用 flowchart。
  • TD / TB 是从上到下，LR 是从左到右，RL 是从右到左，BT 是从下到上。
  • -->|标签| 给箭头加说明，-.-> 是虚线箭头，==> 是粗箭头。
  • 节点 ID 和显示文字可以分开，复杂文案最好写在括号或引号里。

一个更像真实文档的例子：

Codemermaid
flowchart TD  subgraph client[客户端]    edit[编辑内容]    request[提交保存请求]  end   subgraph server[服务端]    auth{权限通过?}    validate{内容合法?}    write[(写入数据库)]  end   edit --> request  request --> auth  auth -->|否| denied[返回 403]  auth -->|是| validate  validate -->|否| invalid[返回校验错误]  validate -->|是| write  write --> ok[返回成功]

流程图最容易犯的错是把不同抽象层揉在一起。比如“用户点击按钮”“服务端鉴权”“数据库索引策略”都很重要，但它们不一定适合出现在同一层图里。图不是收纳箱，不能什么都往里塞。

第五层：用时序图讲清调用顺序

时序图适合解释“谁和谁说了什么，顺序是什么”。它比流程图更适合 API、消息队列、登录、支付、发布等交互场景。

Codemermaid
sequenceDiagram  autonumber  participant U as 用户  participant C as 前端  participant A as API  participant D as 数据库   U->>C: 点击发布  C->>A: POST /articles/:id/publish  A->>D: 写入发布记录  D-->>A: 返回结果  A-->>C: 发布成功  C-->>U: 显示成功状态

常用语法：

  • participant A as API：给参与者起一个短 ID 和显示名。
  • ->>：发送消息。
  • -->>：返回消息。
  • autonumber：自动编号，适合接口流程说明。
  • Note over A,B: 文案：在参与者上方加说明。
  • alt / else / end：表达分支。
  • loop / end：表达循环。

带分支的例子：

Codemermaid
sequenceDiagram  participant C as 前端  participant A as API  participant D as 数据库   C->>A: 提交保存  A->>A: 校验权限和内容  alt 校验通过    A->>D: 保存正文    D-->>A: 保存成功    A-->>C: 200 OK  else 校验失败    A-->>C: 400 Bad Request  end

时序图不要写成接口日志回放。图里只保留理解流程必须知道的消息，错误码、字段名和 payload 细节放在正文或表格里。图负责让你看懂路，正文负责让你看懂规则。两者分工明确，之后维护起来会少一点精神损耗。

第六层：用状态图约束生命周期

状态图适合解释一个对象能处在哪些状态，以及状态之间允许怎么转换。它比文字里的“可以、可能、一般情况下”更可靠，因为非法路径一眼就能看出来。

Codemermaid
stateDiagram-v2  [*] --> Draft  Draft --> Reviewing: 提交审核  Reviewing --> Published: 通过  Reviewing --> Draft: 驳回  Published --> Archived: 归档  Archived --> [*]

适合用状态图的场景：

  • 订单、文章、任务、工单、账号等有明确生命周期的对象。
  • 权限或审核状态比较容易绕晕。
  • 你需要和产品、后端、前端确认“哪些流转被允许”。
  • 你想在测试用例里覆盖关键状态跳转。

状态图的好处是它会逼你把“没有说清楚的状态”说清楚。比如“审核中能不能直接归档”“已发布能不能改回草稿”，这种问题靠散文很容易漏，靠状态图很难装作没看见。

第七层：用 ER 图讲数据关系

ER 图适合表达实体之间的关系，不适合把数据库所有字段原样搬进文档。官方文档也提醒，ER 图可以从抽象逻辑模型一直画到物理表结构；写团队文档时，通常只放关键实体和关键字段就够。

Codemermaid
erDiagram  AUTHOR ||--o{ ARTICLE : writes  ARTICLE ||--o{ COMMENT : has  ARTICLE }o--|| CATEGORY : belongs_to   AUTHOR {    string id PK    string name  }   ARTICLE {    string id PK    string title    string author_id FK    string category_id FK  }   COMMENT {    string id PK    string article_id FK    string body  }   CATEGORY {    string id PK    string name  }

关系符号刚开始看着像密码，其实规律很简单：中间的 -- 是连线，两边的符号分别贴着左右两个实体，表示这一侧的数量约束。注意，多的一侧在左边和右边写法会镜像，所以不要只背一个形状。

含义左侧写法右侧写法
零个或一个 | ` | o``o`
恰好一个 | ` | | ` | ``
零个或多个}oo{
一个或多个 | `} | ``{`

常见组合可以这样读：

写法含义
` | | -- | | `一对一
` | | --o{`一个对零个或多个
` | | -- | {`一个对一个或多个
`}o-- | | `零个或多个对一个
` | o-- | | `零个或一个对一个
}o--o{零个或多个对零个或多个

冒号后面的文字是关系说明，比如 : writes、: has、: belongs_to。所以 ARTICLE }o--|| CATEGORY : belongs_to 可以读成：多篇或零篇文章属于一个分类；ORDER ||--|{ ORDER_ITEM : contains 可以读成：一个订单包含一个或多个订单项。嗯，关系符号看起来像咒语，但其实是很务实的缩写。

ER 图要克制。别把每个 created_at、updated_at 都画进去，除非它们正是你要解释的重点。字段越堆越多，图就越像一份很努力但很难读完的“数据库简历”。

第八层：用甘特图、时间线和脑图讲计划与结构

甘特图适合表达“某段时间内做什么”。它不是项目管理系统，但很适合放在方案文档、发布说明和里程碑计划里。

Codemermaid
gantt  title 文档改造计划  dateFormat  YYYY-MM-DD  axisFormat  %m-%d   section 准备  梳理资料       :done,    prep, 2026-07-01, 2d  确认范围       :active,  scope, after prep, 1d   section 编写  完成初稿       :draft,   after scope, 3d  Review 修订    :review,  after draft, 2d   section 发布  合并发布       :milestone, release, after review, 0d

甘特图里的任务元数据用冒号和逗号分隔。拿这一行举例：

Code
梳理资料 :done, prep, 2026-07-01, 2d

它可以拆成四段：

  • 梳理资料：显示在图上的任务名称。
  • done：任务状态，可省略；常见状态还有 active、crit、milestone。
  • prep：任务 ID，后面可以用 after prep 引用它。
  • 2026-07-01, 2d：开始时间和持续时间；也可以把开始时间写成 after prep。

常见标记有：

  • done：已完成。
  • active：进行中。
  • crit：关键任务。
  • milestone：里程碑。
  • after taskId：接在某个任务后面。

如果你只想表达事件顺序，不关心持续时间，可以用时间线：

Codemermaid
timeline  title 发布节奏  2026-07-01 : 完成草稿  2026-07-03 : 完成评审 : 冻结范围  2026-07-05 : 发布公开版

如果你想表达层级结构，可以用 Mindmap。它适合快速整理主题和分支，不适合放太多细节。

Codemermaid
mindmap  root((Mermaid))    入门      流程图      时序图    文档      README      方案说明    检查      预览      渲染

注意，Mindmap 和 Timeline 在官方文档里带有实验性质提示，具体平台支持可能会滞后。公开文档如果要保证兼容，优先使用流程图、时序图、状态图、ER 图和甘特图这些更常见的图形。

第九层：用 Git 图讲分支策略

GitGraph 适合解释分支、提交和合并。它对开发流程文档很有用，尤其是团队约定 release、hotfix、feature branch 的时候。

Codemermaid
gitGraph  commit id: "init"  branch feature  commit id: "docs"  commit id: "tests"  checkout main  commit id: "hotfix"  merge feature

常用命令很少：

  • commit：在当前分支提交。
  • branch feature：创建并切到新分支；后面的提交会落在这个新分支上。
  • checkout main：切换分支。
  • merge feature：把指定分支合并到当前分支。

Git 图不要追求还原真实历史。真实历史可以用 git log --graph 看，文档里的 GitGraph 应该表达策略，而不是把每次临时提交都供起来展览。

第十层：配置和样式别抢戏

Mermaid 支持主题和配置。官方文档列出的内置主题包括 default、neutral、dark、forest 和 base；其中 base 是用于自定义变量的基础主题。

单张图的配置建议用 frontmatter。旧的 directives 从 Mermaid v10.5.0 开始已被官方标记为 deprecated，新的文档不要再主动用它。

Codemermaid
---config:  theme: neutral---flowchart LR  draft[草稿] --> review[评审]  review --> publish[发布]

如果你是在网站里集成 Mermaid，全局配置通常由站点代码里的 mermaid.initialize() 控制；如果你只是写 Markdown 文档，优先使用平台默认样式。图的主角是关系，不是颜色。过度配色经常让图看起来很忙，却没有多说半句话。

样式的正确使用方式是“提高可读性”，不是“证明我发现了主题配置”。一张图如果逻辑不清楚，换十套颜色也只是让它换着方式不清楚。

第十一层：把 Mermaid 放进团队流程

Mermaid 最适合放在这些地方：

  • README：解释项目结构、启动流程、部署链路。
  • 方案文档：解释模块关系、数据流、状态机。
  • PR 描述：解释本次改动前后的流程差异。
  • 接口文档：解释调用顺序、错误路径、重试策略。
  • 复盘文档：解释事故链路、时间线和修复计划。

推荐写法：

  1. 先用一句话说明这张图要解释什么。
  2. Mermaid 图只放核心路径。
  3. 图下面用文字补充规则、边界和例外。
  4. 节点 ID 用稳定英文，显示文字可以用中文。
  5. 每次改业务规则时，同步改图。
  6. 提交前用目标平台预览，或者粘到 Mermaid Live Editor 验证。

一个文档片段可以长这样：

Codemarkdown
下面这张图只描述发布主路径，不包含导入、回滚和定时发布。 ```mermaidflowchart TD  draft[草稿] --> review[提交审核]  review -->|通过| published[已发布]  review -->|驳回| draft``` 补充规则： - 已发布内容只能通过新版本修改。- 驳回必须写明原因。- 定时发布走独立任务队列，不在本图展开。

图和文字要配合。只放图，你回头看时可能会猜；只放文字，又很容易迷路。两者都写一点，以后回看文档时才不用在图外脑补半天。

第十二层：常见坑提前避开

Mermaid 很轻，但不是没有脾气。

  • 不同平台内置的 Mermaid 版本可能不同。本文查阅时官方文档页面显示 11.16.0（2026-07），实际使用时请以官方文档和目标平台为准。
  • 语法拼错通常会直接让图失败；配置参数拼错有时可能被忽略。写完要预览。
  • end 是 Mermaid 的常见块结束关键字；如果节点文字本身要显示 end，放进引号、括号或换个文案，能避免解析冲突。
  • 中文、空格、标点和特殊字符多的节点，尽量放进 []、(), {} 或引号里。
  • 一张图不要承载太多抽象层。节点太多、交叉线太多、说明太多时，拆图比调样式更有效。
  • 不可信用户输入不要直接拿去网页渲染。公开站点如果支持用户提交 Mermaid，要关注 Mermaid 的安全配置和沙箱策略。
  • AI 生成 Mermaid 时尤其要验证。大模型很会编故事，也很会编不存在的语法。

最实用的检查清单：

  • 这张图不用正文解释，你能不能看出主路径？
  • 图里有没有和正文矛盾的状态、分支或字段？
  • 节点是否超过一眼能消化的数量？
  • 是否用了目标平台支持的图类型？
  • 是否在真实渲染环境里预览过？

如果这五个问题都过了，图通常不会太差。如果其中三个都没过，那不是 Mermaid 图，是一份需要被重新组织的文字。

复制即用模板

流程图模板：

Codemermaid
flowchart TD  start([开始]) --> step1[步骤一]  step1 --> decision{是否通过?}  decision -->|是| success([完成])  decision -->|否| retry[修正后重试]  retry --> step1

时序图模板：

Codemermaid
sequenceDiagram  autonumber  participant C as Client  participant A as API  participant S as Service   C->>A: Request  A->>S: Handle  S-->>A: Result  A-->>C: Response

状态图模板：

Codemermaid
stateDiagram-v2  [*] --> Created  Created --> Active: activate  Active --> Suspended: suspend  Suspended --> Active: resume  Active --> Closed: close  Closed --> [*]

ER 图模板：

Codemermaid
erDiagram  USER ||--o{ ORDER : places  ORDER ||--|{ ORDER_ITEM : contains  PRODUCT ||--o{ ORDER_ITEM : appears_in   USER {    string id PK    string name  }   ORDER {    string id PK    string user_id FK  }   ORDER_ITEM {    string id PK    string order_id FK    string product_id FK  }   PRODUCT {    string id PK    string name  }

甘特图模板：

Codemermaid
gantt  title 项目计划  dateFormat  YYYY-MM-DD   section 阶段一  任务 A :a1, 2026-07-01, 2d  任务 B :after a1, 3d   section 阶段二  里程碑 :milestone, after a1, 0d

最后再给一个很现实的建议：写 Mermaid 时，先画丑一点但正确的图。正确的图可以慢慢变好看；错误的图就算很漂亮，也只是很漂亮地误导你和后来维护的人。

参考资料

本文基于 Mermaid 官方文档整理，查阅时间为 2026-07-09。

  • Mermaid About: https://mermaid.js.org/intro/
  • Mermaid User Guide: https://mermaid.js.org/intro/getting-started.html
  • Diagram Syntax: https://mermaid.js.org/intro/syntax-reference.html
  • Flowcharts Syntax: https://mermaid.js.org/syntax/flowchart.html
  • Sequence diagrams: https://mermaid.js.org/syntax/sequenceDiagram.html
  • State diagrams: https://mermaid.js.org/syntax/stateDiagram.html
  • Entity Relationship Diagrams: https://mermaid.js.org/syntax/entityRelationshipDiagram.html
  • Gantt diagrams: https://mermaid.js.org/syntax/gantt.html
  • GitGraph Diagrams: https://mermaid.js.org/syntax/gitgraph.html
  • Configuration: https://mermaid.js.org/config/configuration.html
  • Theme Configuration: https://mermaid.js.org/config/theming.html
  • Directives: https://mermaid.js.org/config/directives.html
0