新的
不喜欢广告？ 去 无广告 今天
Mermaid 图表 在不点击任何内容的情况下，使用 Markdown 实现文档架构
更新于
Google Slides中的图表将在下一个迭代周期后变得过时。Mermaid允许您以纯文本形式编写流程图、序列图、实体关系图等，并将其保存在README文件中，在GitHub上渲染，并与您的代码一起进行版本控制。以下是您实际需要的每种图表类型，以及真实的语法示例。
广告 移除？
你当初画架构图时是准确的，那是在三个迭代周期前。现在它被保存在一个没人更新的共享Google幻灯片中，而描述该服务的工程师已经转到了其他团队。这听起来很熟悉吗？
Mermaid图表从根本上解决了这个问题。与其使用一个位于代码库之外的拖放式画布，你只需用文本编写图表——一种简单的Markdown风格语法，它被保存在README中，与代码一起受版本控制，并在任何支持Markdown的地方渲染。当架构发生变化时，你只需修改一个文本文件，差异变更就能完整地讲述整个故事。
Mermaid是什么（以及为什么图表作为代码很重要）
Mermaid是一种开源的图表语言，它能从纯文本中渲染出图表。你在一个被包围的代码块中编写流程图；一个渲染器（或一个支持Mermaid的查看器）会将其转换为SVG图表。无需账户，无需导出步骤，无需“该图表格式不被此设备支持”。
‘图表作为代码’这一方法在以下几个具体方面体现出其价值：
- 版本控制 —— 图表存在于Git中。你可以对比差异、回滚，并将其与描述它的代码所在的同一拉取请求（PR）关联。
- 无厂商锁定 —— 纯文本是可移植的。更换渲染器、fork仓库、导出到Confluence——源文件始终可读。
- 始终贴近代码 —— 与服务代码位于同一仓库中的图表，比存放在共享幻灯片中的图表更有可能保持准确。
- 易于自动化 —— 你可以使用脚本或大语言模型（LLM）从代码（数据库模式、API规范、CI流水线）生成Mermaid语法。
在深入学习各种图表类型之前，你可以立即预览任何Mermaid语法——无需本地安装——使用 iotools.cloud上的Mermaid图表渲染器。粘贴、查看结果、迭代。你可以结合本指南运行所有示例。
流程图：工作马
流程图是Mermaid中最常见的图表类型，原因充分——它能处理从简单决策树到复杂多服务流程的各种场景。以下是涵盖90%真实使用场景的语法：
flowchart TD
A[User submits form] --> B{Validation passes?}
B -- Yes --> C[Save to database]
B -- No --> D[Return error to client]
C --> E[Send confirmation email]
E --> F([End])关于流程图语法，有几个要点需要了解：
- 方向:
TD(自上而下)，LR(自左至右)，BT(自下而上)，RL(自右至左) - 节点形状:
[rectangle],(rounded),([stadium]),{diamond},((circle)),[(cylinder)] - 边标签:
-- label -->或-->|label| - 子图: 可视化地将相关节点分组
子图特别适用于展示服务边界：
flowchart LR
subgraph Frontend
UI[React App]
end
subgraph Backend
API[FastAPI]
DB[(PostgreSQL)]
end
UI --> API
API --> DB序列图：展示API调用流程
当需要展示系统间交互的顺序时——例如API调用链、认证流程、Webhook序列——序列图是正确的工具。它能清晰地展示时间顺序和责任归属，而流程图无法做到这一点。
sequenceDiagram
participant Client
participant API Gateway
participant Auth Service
participant Users DB
Client->>API Gateway: POST /login {email, password}
API Gateway->>Auth Service: Validate credentials
Auth Service->>Users DB: SELECT user WHERE email=?
Users DB-->>Auth Service: User record
Auth Service-->>API Gateway: JWT token
API Gateway-->>Client: 200 OK {token}实线箭头 (->>) 表示请求；虚线箭头 (-->>) 表示响应。 participant 声明控制了各个框在图顶部的排列顺序。你还可以使用 actor 表示人类参与者， activate/deactivate 表示处理时间，和 loop 或 alt 块表示条件流程。
实体-关系图：数据库模式在文档中的体现
每个拥有数据库模式的服务的README中都应包含ER图。Mermaid的ER语法简洁明了，并且内置了基数表示：
erDiagram
USER {
int id PK
string email
string name
timestamp created_at
}
ORDER {
int id PK
int user_id FK
decimal total
string status
}
ORDER_ITEM {
int id PK
int order_id FK
int product_id FK
int quantity
}
USER ||--o{ ORDER : "places"
ORDER ||--|{ ORDER_ITEM : "contains"基数表示： || 表示恰好一个， o| 表示零或一个， o{ 表示零或多个， |{ 表示一个或多个。关系标签（“位置”、“包含”）放在引号内。
状态图：建模工作流和状态机
当你有一个实体在不同状态之间移动时——例如订单、订阅、CI作业——状态图比流程图更精确。Mermaid的状态图语法直接对应于你在代码中定义的状态机：
stateDiagram-v2
[*] --> Pending
Pending --> Processing : payment received
Processing --> Shipped : warehouse picks order
Shipped --> Delivered : carrier confirms
Shipped --> Returned : customer initiates return
Delivered --> [*]
Returned --> Refunded : refund processed
Refunded --> [*][*] 标记起始和结束状态。转换携带触发事件。你可以嵌套状态以表示复合状态，并使用 note 块为转换添加额外上下文。
类图：面向对象结构用于入职文档
类图在向工程师介绍面向对象代码库或记录领域模型时最为有用。Mermaid支持继承、接口、组合和方法签名：
classDiagram
class Animal {
+String name
+int age
+makeSound() void
}
class Dog {
+String breed
+fetch() void
}
class Cat {
+boolean isIndoor
+purr() void
}
Animal <|-- Dog : extends
Animal <|-- Cat : extends可见性修饰符遵循UML约定： + public， - private， # protected。关系箭头涵盖关联 (-->)，继承 (<|--)，组合 (*--)，和聚合 (o--).
在Mermaid原生支持的工具中
Mermaid真正的优势在于它在开发者已使用的工具中原生支持：
- GitHub —— Mermaid被包围的代码块 (
```mermaid) 从2022年起在README、问题、拉取请求描述和Wiki中自动渲染。 - GitLab —— 在Markdown文件和Wiki页面中原生支持Mermaid。
- Notion —— 将Mermaid代码块粘贴到一个设置为“Mermaid”的代码块中，即可原生渲染。
- Visual Studio Code —— Markdown预览中的Mermaid支持扩展可在内置预览面板中渲染图表。
- Obsidian —— Mermaid无需任何插件即可原生渲染。
- Docusaurus, MkDocs, Astro —— 所有主要静态站点生成器都支持Mermaid插件。
- Confluence —— 通过Mermaid Diagrams for Confluence应用实现。
如果你的文档将发布到GitHub或GitLab，Mermaid图表无需任何配置即可直接使用。
潜在问题及何时使用其他工具
Mermaid并非适用于所有场景。需要注意以下几点：
- 复杂布局 —— Mermaid的自动布局算法在大型图中并不总是产生清晰的结果。如果你有50个以上的节点且存在大量交叉边，可能需要手动重构或拆分图表。
- Confluence渲染 —— Confluence原生不支持Mermaid，需要付费应用。如果团队使用Confluence，需为此预算或改用draw.io。
- 非标准图表类型 —— 网络图、部署图和C4架构图需要变通方案或支持不佳。
- 样式控制 —— Mermaid的主题选项有限。对于需要自定义颜色和字体的品牌化图表，你将花费大量时间与渲染器对抗。
值得了解的主要替代方案：
- PlantUML —— 语法较旧且更冗长，但UML支持更丰富，Confluence集成更好。需要本地Java或服务器端渲染器。
- D2 —— 新的“图表作为代码”工具，布局控制更清晰，对大型图表处理更好。生态系统采用率低于Mermaid，但发展迅速。
- draw.io / Excalidraw —— 用于需要精确视觉控制且不介意图表脱离版本控制的场景的GUI工具。
对于大多数开发者文档——服务README、API流程、入职指南——Mermaid能够很好地满足需求，仅需学习曲线即可获得其价值。
无需安装即可预览Mermaid
如果你正在尝试语法或希望与没有本地渲染器的同事分享图表， iotools.cloud上的Mermaid图表渲染器 提供无需注册、无需安装、无需配置的实时预览。粘贴你的Mermaid代码，查看渲染结果，并复制输出。
它适用于在提交前检查语法、在Slack消息中分享渲染版本，或在最终将图表粘贴到README前进行原型设计。
从流程图开始
如果你从未写过Mermaid图表，从流程图开始。选择你代码库中一直想记录的一个流程——例如请求生命周期、后台作业、部署流水线——在接下来的10分钟内用Mermaid语法写出来。将其粘贴到README中的一个 ```mermaid 代码块中并提交。GitHub将自动渲染它。
这个与代码相邻且受版本控制的图表，其价值远超一个无人信任的幻灯片。
