常用图表 Mermaid

2026-07-14 · devops · 3 次阅读

为什么用 Mermaid

文档里的架构图、时序图、排期表如果靠截图维护，很容易过期：改一处业务就得重画、重传。Mermaid 用纯文本描述图表，和 Markdown 同库同审，改几行源码即可重新出图，适合设计说明、接口约定、排期与表结构这类需要「随文演进」的内容。

主要好处：

可版本管理：diff 看得见，不会只留下一张来历不明的图
改动成本低：加节点、改关系不必开绘图软件
随文渲染：在支持 Mermaid 的文章站或编辑器里自动变成 SVG
类型覆盖广：流程、时序、甘特、ER、架构、Git、饼图、思维导图、状态图等

怎么写

在 Markdown 里用围栏代码块，第一行语言标成 mermaid，中间写图语法，即可：

```mermaid
flowchart LR
  A[开始] --> B[结束]
```

注意：

围栏必须成对闭合；语言名必须是 mermaid（不要写成 mmd）
标签含空格、括号、中文特殊符号时，优先用双引号：id["L0 · 接入层"]
脱敏：用「网关 / 业务服务」等角色名，避免写主机名、内网地址、真实域名
版本：文内示例按 Mermaid 10+；architecture-beta 需 11.1+，且该类型标题宜用 ASCII

颜色是怎么来的

写图时一般 不用手写颜色。站点在渲染时统一配色：

引擎主题变量：mermaid.initialize 使用 theme: "base"，把集群底设为透明（clusterBkg），节点用浅绿表面色，文字与连线贴近站点 CSS 变量
页面 CSS：对渲染结果容器（如 .doc-mermaid-wrap）再压一层——外框透明、.cluster rect 透明、节点填充/描边跟文章主题走

当前取向是 「外框透气、只给节点轻轻填色」，避免默认白底框贴在淡绿页面上发跳。个别图若要局部强调，可在 flowchart 等语法里用 style / classDef 临时覆盖，多数情况保持默认即可。

下文按类型给出可直接复制的示例。

1. 流程图 flowchart

flowchart TB
  subgraph L0["接入层"]
    GW[网关]
    AUTH[鉴权]
  end
  subgraph L1["业务层"]
    API[业务 API]
    JOB[定时任务]
  end
  subgraph L2["数据层"]
    DB[(关系数据库)]
    CACHE[(缓存)]
  end
  GW --> AUTH --> API
  API --> DB
  API --> CACHE
  JOB --> DB

方向常用：TB（上→下）、LR（左→右）。节点标签含特殊字符时用双引号：id["标题（说明）"]。

2. 时序图 sequenceDiagram（接口调用）

sequenceDiagram
  actor U as 客户端
  participant G as 网关
  participant S as 业务服务
  participant D as 数据存储

  U->>G: 提交请求
  G->>G: 校验令牌
  G->>S: 转发业务调用
  S->>D: 读写数据
  D-->>S: 结果
  S-->>G: 业务响应
  G-->>U: HTTP 结果

  Note over S,D: 失败时可重试或降级

箭头：->> 同步请求，-->> 返回；participant / actor 区分角色。

3. 甘特图 gantt（项目排期）

gantt
  title 示例发布排期
  dateFormat YYYY-MM-DD
  axisFormat %m-%d
  section 准备
    需求冻结           :a1, 2026-03-01, 5d
    环境与依赖就绪     :a2, after a1, 4d
  section 开发
    核心接口           :b1, after a2, 10d
    前端联调           :b2, after b1, 5d
  section 发布
    预发验证           :c1, after b2, 3d
    正式发布           :milestone, m1, after c1, 0d

after 表示依赖上一任务；milestone 为零工期里程碑。

4. ER 图 erDiagram（表关系）

erDiagram
  USER ||--o{ ORDER : places
  USER {
    string id PK
    string name
    string email
  }
  ORDER ||--|{ ORDER_ITEM : contains
  ORDER {
    string id PK
    string user_id FK
    datetime created_at
  }
  ORDER_ITEM {
    string id PK
    string order_id FK
    string sku
    int qty
  }
  PRODUCT ||--o{ ORDER_ITEM : "referenced by"
  PRODUCT {
    string sku PK
    string title
    decimal price
  }

基数：||--o{ 一对多，||--|{ 一对至少一，}|--|{ 多对多。

5. 架构图 architecture-beta（云 / 容器）

architecture-beta
  group edge(cloud)[Edge]
  group app(server)[App]
  group data(disk)[Data]

  service gw(internet)[Gateway] in edge
  service api(server)[API] in app
  service worker(server)[Worker] in app
  service db(database)[DB] in data
  service obj(disk)[ObjectStore] in data

  gw:R -- L:api
  api:B -- T:db
  api:R -- L:worker
  worker:B -- T:obj

说明：

group / service 图标名：cloud、server、database、disk、internet 等
连线用 --，两侧用 L|R|T|B 指定锚点（如 gw:R -- L:api）
当前 Mermaid 11.x 的 architecture-beta 标题仅稳妥支持 ASCII（中文会出现 unexpected character: [ 解析失败）；中文说明写在图外正文即可
实验特性，语法随版本可能变化

6. Git 分支图 gitGraph

gitGraph
  commit id: "init"
  commit id: "add feature stub"
  branch develop
  checkout develop
  commit id: "wip"
  branch feature/login
  checkout feature/login
  commit id: "login api"
  commit id: "login ui"
  checkout develop
  merge feature/login id: "merge login"
  checkout main
  merge develop id: "release"
  commit id: "tag v1.0"

适合讲分支策略（main / develop / feature），勿写真实仓库地址。

7. 饼图 pie

pie showData
  title 流量来源占比（示例）
  "搜索" : 42
  "直接访问" : 28
  "外链" : 18
  "社媒" : 12

数值为相对权重；showData 在扇区旁显示数值。

8. 思维导图 mindmap

mindmap
  root((运维知识库))
    平台
      计算
      网络
      存储
    中间件
      消息
      缓存
      配置中心
    可观测
      指标
      日志
      链路
    发布
      灰度
      回滚

层级用缩进；根节点可用 ((…)) 圆角样式。

9. 状态图 stateDiagram-v2

stateDiagram-v2
  [*] --> Draft
  Draft --> Review: 提交
  Review --> Draft: 驳回
  Review --> Published: 通过
  Published --> Archived: 下线
  Archived --> [*]

  state Review {
    [*] --> Waiting
    Waiting --> Checking: 自动检查
    Checking --> Waiting: 人工介入
    Checking --> [*]
  }

[*] 表示起止；可嵌套子状态描述审批等流程。

10. 类图 classDiagram（补充）

classDiagram
  class Animal {
    +String name
    +eat()
  }
  class Dog {
    +bark()
  }
  Animal <|-- Dog
  Animal "1" --> "*" Leg : has

适合表达模块 / DTO 关系，非 UI 流程图。

写作提示

点	说明
围栏语言	必须标记为 `mermaid`
特殊字符	标签用双引号；箭头在围栏内原样写 `-->`
脱敏	用角色名、网关、业务服务等泛称，避免主机名、内网地址、真实域名
版本	渲染失败时先查当前 Mermaid 是否支持该图类型

更完整语法见 Mermaid 官方文档。

igozhang