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

更新时间：2026-07-09

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

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

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

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

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

Mermaid 的核心就三步：

最小例子长这样：

翻译成人话就是：

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

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

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

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

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

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

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

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

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

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

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

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

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

判断方式可以更直接：

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

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

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

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

这里有几件事值得记：

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

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

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

常用语法：

带分支的例子：

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

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

适合用状态图的场景：

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

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

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

常见组合可以这样读：

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

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

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

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

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

它可以拆成四段：

常见标记有：

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

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

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

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

常用命令很少：

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

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

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

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

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

Mermaid 最适合放在这些地方：

推荐写法：

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

下面这张图只描述发布主路径，不包含导入、回滚和定时发布。

补充规则：- 已发布内容只能通过新版本修改。- 驳回必须写明原因。- 定时发布走独立任务队列，不在本图展开。

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

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

最实用的检查清单：

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

流程图模板：

时序图模板：

状态图模板：

ER 图模板：

甘特图模板：

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

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