Mermaid：用代码画图，让文档一图胜千言
Mermaid：用代码画图，让文档一图胜千言
为什么要在文档里写代码画图？因为 Mermaid 让你的图表像代码一样可版本控制、可协作、可复用
如果你用过 Markdown 写技术文档，一定在 GitHub 的 README 或 Obsidian 笔记里见过这样的代码块：
```mermaid
graph TD
A[开始] --> B[结束]
```
它渲染出来的不是一段代码，而是一张流程图。这就是 Mermaid——当今最流行的"文本即图表"方案。今天我们来聊聊它的诞生故事、它能画什么、以及 10 分钟就能上手的核心语法。
一、诞生故事
时间回到 2014 年。那时想在文档里放一张流程图，常见的做法是：
- 打开 Visio 或 draw.io，拖拽出想要的图形
- 导出为 PNG 或 SVG，嵌入文档
- 改动后重新截图、替换、提交
这个过程既繁琐又脆弱——更新一次流程图相当于重画一张，更糟糕的是二进制截图在 Git 中完全不可 diff。如果有同事改了流程但你忘了同步截图，文档和代码就脱节了。
挪威开发者 Knut Sveidqvist 受够了这种体验。他想：能不能像 Markdown 一样，用纯文本定义图表，然后自动渲染？ 这样图表就和代码一起存在于文本文件中，Git diff 一目了然，改动只需要改几行文字。
于是他创造了一个 JavaScript 库，命名为 Mermaid（美人鱼）。这个名字有两层寓意：
- 像人鱼一样在两个世界之间优雅游走——纯文本的可读性和图表的直观性
- 灵感来自《小美人鱼》的故事——某种「从另一个世界带来的礼物」
2015 年，项目在 GitHub 开源后迅速获得关注。2017 年 GitHub 将 Mermaid 集成到 Markdown 渲染引擎中——从此只要在 .md 文件中写 mermaid 代码块，GitHub 会自动渲染为图表。这是 Mermaid 爆发的转折点。
如今，Mermaid 被 Obsidian、GitLab、Notion（通过插件）、Typora 等几乎所有主流 Markdown 平台支持，每月 npm 下载量超过 500 万，成为事实上的"文本图表标准"。
二、Mermaid 能画什么？
Mermaid 支持十多种图表类型，以下按使用频率介绍最常用的几种：
1. 流程图（Flowchart）
最常用的图表类型。 用节点和箭头展示流程、决策树或算法逻辑。
```mermaid
graph TD
A[起床] --> B{今天周末？}
B -->|是| C[睡懒觉]
B -->|否| D[上班]
C --> E[开心]
D --> F[加油]
```
2. 时序图（Sequence Diagram）
展示多个参与者之间的消息传递，按时间顺序从上往下排列。适合描述 API 调用链、用户登录流程等。
```mermaid
sequenceDiagram
participant 用户
participant 前端
participant 后端
用户->>前端: 点击登录
前端->>后端: POST /api/login
后端-->>前端: 返回 token
前端-->>用户: 跳转首页
```
3. 类图（Class Diagram）
展示系统类结构、接口、继承关系。适合技术架构文档或面向对象设计。
```mermaid
classDiagram
class Animal {
+String name
+eat() void
}
class Dog {
+bark() void
}
class Cat {
+meow() void
}
Animal <|-- Dog
Animal <|-- Cat
```
4. 状态图（State Diagram）
展示状态与转移，适合描述订单状态机、工作流等。
```mermaid
stateDiagram-v2
[*] --> 待支付
待支付 --> 已支付: 支付成功
待支付 --> 已取消: 超时取消
已支付 --> 已发货
已发货 --> 已完成
已完成 --> [*]
```
5. 饼图（Pie Chart）
轻量级数据可视化，语法极其简单。
```mermaid
pie
title 编程语言使用占比
"JavaScript" : 40
"Python" : 25
"TypeScript" : 20
"其他" : 15
```
6. 时间线（Timeline）
展示项目里程碑、历史演进、路线图。
```mermaid
timeline
title Mermaid 发展历程
2014 : Knut 创建项目
2015 : 在 GitHub 开源
2017 : GitHub 原生支持
2020 : Obsidian 集成
2024 : npm 月下载量 500 万+
```
7. Git 分支图（Git Graph）
可视化展示 Git 分支合并历史，非常酷。
```mermaid
gitGraph
commit
branch feature
checkout feature
commit
commit
checkout main
merge feature
commit
```
8. 思维导图（Mindmap）
树状层级结构，适合头脑风暴和知识整理。
```mermaid
mindmap
root((Mermaid))
流程图
时序图
类图
状态图
饼图
```
注：思维导图是相对较新的图表类型，部分平台可能暂不支持。
三、核心语法（10 分钟入门）
Mermaid 的语法和 Markdown 有着相同的精神：用你熟悉的符号表示结构。下面从最常用的流程图开始，循序渐进。
1. 节点定义
| 形状 | 语法 | 说明 |
|---|---|---|
| 矩形 | A[文本] |
默认节点 |
| 圆角矩形 | A(文本) |
开始/结束 |
| 菱形 | A{文本} |
条件判断 |
| 圆形 | A((文本)) |
特殊标记 |
| 六边形 | A{{文本}} |
准备/预处理 |
2.连线方式：
A --> B 实线箭头
A --- B 实线无箭头
A -.- B 虚线
A ==> B 粗线箭头
A -- 文本 --> B 带标签的箭头
2. 方向定义
graph TD 从上到下
graph LR 从左到右
graph BT 从下到上
graph RL 从右到左
3. 子图（Subgraph）
```mermaid
graph TB
subgraph 前端
A[React] --> B[API 层]
end
subgraph 后端
C[Node.js] --> D[数据库]
end
B --> C
```
4. 时序图
```mermaid
sequenceDiagram
participant A
participant B
A ->> B: 消息
B -->> A: 响应
```
5. 类图
```mermaid
classDiagram
class 类名 {
+公有属性
-私有属性
+方法() 返回值
}
class 子类
类名 <|-- 子类
```
6. 主题切换
在代码块开头加上 %%{init: {'theme': 'dark'}}%% 即可切换为暗色主题：
```mermaid
%%{init: {'theme': 'dark'}}%%
graph TD
A[暗色主题] --> B[适合夜间阅读]
```
主题选项：default、dark、neutral、forest。
7. 点击交互
Mermaid 支持给节点添加点击跳转链接（需渲染平台支持）：
click A "https://example.com" "跳转到详情"
Mermaid 代码块的缩进和空格是敏感的。 如果图表渲染不正常，先检查：
- 节点文本是否用了正确的括号（
[]、{}、()） - 缩进是否一致（用空格，不要混用 Tab 和空格）
- 中文和特殊字符的节点建议用引号包裹，如
A["开始操作"]
四、Mermaid、 Draw.io、PlantUML 的对比
| 对比维度 | Mermaid | Draw.io / Excalidraw | PlantUML |
|---|---|---|---|
| 图表定义方式 | 纯文本代码，写完即渲染 | 拖拽图形界面 | 纯文本代码（更古老） |
| Markdown 内嵌 | ✅ 原生支持 | ❌ 需导出截图 | ⚠️ 需插件或服务端 |
| 版本控制 | ✅ Git diff 清晰 | ❌ 二进制文件无法 diff | ✅ 纯文本，diff 清晰 |
| 上手难度 | ⭐ 极低，10 分钟 | ⭐ 零门槛 | ⭐⭐⭐ 语法复杂 |
| 美观度 | ⭐⭐⭐ 自动布局，风格现代 | ⭐⭐⭐⭐⭐ 精细控制 | ⭐⭐ 默认风格偏老 |
| 学习成本 | 10 分钟掌握 80% 常用场景 | 无需学习 | 语法较多，需专门学习 |
| 适用场景 | 文档内嵌、代码注释 | 白板讨论、精细设计稿 | 遗留项目、UML 专项 |
怎么选：
- 写博客、README、Obsidian 笔记 → Mermaid 最快最省心
- 白板讨论、头脑风暴 → Excalidraw / draw.io 更自由
- 复杂 UML 建模 → PlantUML 或专业工具更合适
五、结语
从 2014 年 Knut Sveidqvist 的一个"用文本画图"的想法，到今天成为 GitHub 上最受欢迎的图表方案之一，Mermaid 完成了和 Markdown 相似的使命：让技术写作者专注于内容，而不是排版工具。
它的成功来自一个简单而深刻的洞察：文档和图表应该是同一件事。 当你修改代码时顺便改两行 Mermaid 就能更新图表，文档才不会过时。
在 Obsidian、GitHub、Notion 等平台的支持下，Mermaid 已经成为现代文档写作的标配能力。Mermaid Live Editor（在线编辑器），用 Mermaid 画出你的第一个流程图吧
资源链接：
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
5
0- 0
已为社区贡献4条内容
所有评论(0)