ReaderMX.
数据STUDIO

Mermaid：用写代码的方式画图，AI 时代的技术文档终局方案

数云朵君约 10 分钟
Image

先看效果。

下面这段 8 行文本，就是一个完整的用户登录流程图：

flowchart TD
    A[用户输入账号密码] --> B{验证信息}
    B -- 通过 --> C[生成 JWT Token]
    B -- 失败 --> D[返回 401 错误]
    C --> E[跳转首页]
    D --> F[提示重新输入]
    F --> A
Image

把它贴进 GitHub README、Obsidian 笔记、或者任何支持 Mermaid 的地方——它自动渲染成一张带箭头的专业流程图。你没有打开任何画图软件，没有拖拽过一个矩形框，没有手动对齐过一根线。这就是 Mermaid 做的事：用 Markdown 一样的文本语法，生成矢量图表。

Mermaid 是 Diagrams as Code 的事实标准——用文本语法生成 20+ 种专业图表，Git 可 diff、AI 可生成、零工具切换。本文覆盖 18 种图表类型的完整语法示例，可直接复制的代码块，加 AI 原生生成演示和踩坑调优。

01一、为什么你应该关心 Mermaid

每个写代码的人都要画图。架构图、流程图、时序图、数据库 ER 图。但不是每个人都"愿意"画图——因为传统的画图方式实在太重了。

你大概经历过这个流程：打开 Draw.io（或 Visio、Figma）→ 从空白画布开始拖矩形 → 连箭头 → 手动对齐 → 导出 PNG → 插入文档 → 第二天需求变了 → 重复以上全部步骤。导出的 PNG 是个二进制文件，Git 不知道你改了哪个节点，同事 review PR 时看到的是一张"已替换"的图片，没法 diff。

Mermaid 换了一种范式：图表即代码（Diagrams as Code）。

图表不再是图片文件，而是嵌在 Markdown 里的文本。这意味着三件事：

1. Git 友好。 Mermaid 源码就是纯文本，git diff 能精确显示你改了什么——"把 Redis 缓存层从主流程里删了"一行行清清楚楚，不用对着两张 PNG 玩找不同。

2. AI 原生兼容。 Claude、GPT-4、Cursor——任何一个 LLM 都能直接输出 Mermaid 语法。你用自然语言描述系统架构，它吐出一段 Mermaid 代码，贴进文档即渲染。这是拖拽工具永远做不到的事：AI 没法帮你拖矩形，但它能帮你写文本。

3. 零工具切换。 你已经在编辑器里了——VS Code、Obsidian、甚至 GitHub 网页端。Mermaid 就在你写文档的地方，不需要打开第三个软件。

这三点，让 Mermaid 从"又一个画图工具"变成了技术文档的终局方案。截止 2026 年 6 月，Mermaid 在 GitHub 上有 88,000+ 颗 Star，npm 周下载量 640 万，800 万+ 开发者在使用它。GitHub、GitLab、Notion、Obsidian、VS Code 全部原生集成。2024 年拿了 Sequoia 和 Microsoft M12 的 $7.5M 种子轮——这不再是一个"小众开源项目"，而是 Diagrams as Code 的事实标准。

02二、5 分钟跑通：环境搭建

你不用装任何新软件。下面四种方式，挑一个你已经在用的。

VS Code：扩展商店搜"Mermaid"，安装 Markdown Preview Mermaid Support。打开任意 .md 文件，写一个 mermaid 代码块，Ctrl+Shift+V 打开预览——实时渲染。

Obsidian：原生支持，零配置。在笔记里写 ```mermaid 代码块，自动渲染。Obsidian 是目前对 Mermaid 支持最好的笔记软件。

GitHub：README、Issue、PR、Wiki——任何 Markdown 区域，mermaid 代码块直接渲染。你现在的项目的 README.md 就能用。

在线 Playground：打开 mermaid.live，左边写代码，右边实时预览，支持导出 SVG / PNG / PDF。

下面进入正题——Mermaid 到底能画多少种图。

03三、核心语法：18 种图表全覆盖

Mermaid v11.15 支持 20+ 种图表类型。以下按使用场景分组，逐一给出完整语法示例。

3.1 流程与结构

Flowchart（流程图）——最常用。节点形状丰富，箭头类型多样，支持 subgraph 分组。

flowchart LR
    A[矩形] --> B(圆角矩形)
    B --> C{菱形判断}
    C --> D[(数据库)]
    C --> E[[子程序]]
    C --> F([体育场形])

    subgraph 前端层
        A
        B
    end
    subgraph 数据层
        D
    end

节点形状速查：[矩形](圆角){菱形}[(数据库)][[子程序]]([体育场])((圆形))>标签]（不对称） /平行四边形/\梯形\。箭头速查：--> 实线 -.-> 虚线 ==> 粗线 --o 圆头 --x 叉头 -->|标签| 带文字。

State Diagram（状态图）——建模工作流、订单生命周期、Agent 状态机。

stateDiagram-v2
    [*] --> 待支付
    待支付 --> 已支付 : 付款成功
    待支付 --> 已取消 : 超时/用户取消
    已支付 --> 已发货 : 仓库出货
    已发货 --> 已完成 : 用户签收
    已发货 --> 退货中 : 申请退货
    退货中 --> 已退款 : 退货入库
    已完成 --> [*]
    已取消 --> [*]
    已退款 --> [*]
Image

[*] 表示起止状态。state 关键字可以定义复合状态（嵌套子状态机）。v11.15 支持 :::className 在复合状态内部使用 CSS 类。

3.2 交互与通信

Sequence Diagram（时序图）——API 调用链、微服务通信、OAuth 流程的首选。

sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as API 网关
    participant S as 认证服务
    participant D as 数据库

    U->>F: 输入账号密码
    F->>A: POST /api/login
    A->>S: 转发认证请求
    S->>D: SELECT user WHERE email=?
    D-->>S: 返回用户记录
    S-->>A: JWT Token
    A-->>F: 200 OK + Token
    F-->>U: 跳转首页

    alt Token 过期
        F->>A: POST /api/refresh
        A-->>F: 新 Token
else 验证失败
        A-->>F: 401 Unauthorized
    end
Image

->> 实线箭头，-->> 虚线箭头。alt/else/end 控制分支，loop/end 循环。v11.14 新增 style ActorName fill:xxx 语法给参与者上色。

Class Diagram（类图）——OOP 设计、代码文档、继承关系可视化。

classDiagram
    class User {
        +String id
        +String email
        +String passwordHash
        +login()
        +logout()
    }
    class Admin {
        +String role
        +banUser(userId)
    }
    class Post {
        +String title
        +String content
        +publish()
    }

    User <|-- Admin : 继承
    User "1" --> "0..*" Post : 发布

关系符号：<|-- 继承、*-- 组合、o-- 聚合、<|.. 实现接口、--> 关联。基数标注在引号内："1""0..*""1..*"。

3.3 数据与存储

ER Diagram（实体关系图）——数据库 schema 文档化。

erDiagram
    USER ||--o{ ARTICLE : 撰写
    USER ||--o{ COMMENT : 发表
    ARTICLE ||--o{ COMMENT : 包含
    ARTICLE }o--o{ TAG : 标签

    USER {
        string id PK
        string email UK
        string display_name
        datetime created_at
    }
    ARTICLE {
        string id PK
        string user_id FK
        string title
        text content
    }
Image

关系：||--|| 一对一、||--o{ 一对多、}o--o{ 多对多。字段类型 + PK/FK/UK 约束一目了然。

3.4 数据可视化

Mermaid 也能覆盖部分 matplotlib 常见的数据可视化场景，包括折线图、柱状图、饼图、桑基图、象限散点图、雷达图和矩形树图。其中 xychart-beta、sankey-beta、radar-beta、treemap-beta 对渲染环境版本要求较高，建议使用 v11.6+。

XY Chart — 折线图。xychart-beta 同时支持 bar 和 line，可以只用折线表达趋势：

Image

XY Chart — 柱状图。单用 bar 做分类对比：

Image

XY Chart — 柱线混合图。bar + line 叠加，一图双指标：

Image

showDataLabelOutsideBar 可在柱外显示数值标签。

Pie Chart（饼图）——数据占比可视化。数值必须是大于 0 的正数。

Image

v11.14 支持 innerHole 配置实现环形图，legend 位置可调（top/bottom/left/right/center）。

Sankey（桑基图）——流量/资金/能源流向分析。语法是三列 CSV：source,target,value。

Image

每个三元组 = 源节点, 目标节点, 流量值。流向宽度自动按比例缩放。【桑基图比较特殊，经过测试，不支持中文】

Radar Chart（雷达图）——多维能力评估、产品对比。v11.6.0 引入，axis 定义维度，curve 定义数据线。

Image

Treemap（矩形树图）——层级占比可视化。缩进表达层级，叶子节点用 "名称": 数值。这是较新的图表类型，语法未来可能变化。

Image

3.5 项目管理

Gantt Chart（甘特图）——项目排期、sprint 计划、里程碑跟踪。

Image

after <id> 表达任务依赖。done / active / crit 控制任务样式。:milestone 生成里程碑标记。

Timeline（时间线）——历史演进、版本发布记录、Roadmap。

Image

GitGraph（Git 分支图）——分支策略文档化。

Image

完美替代"在 README 里用 ASCII art 画 Git 流程"这种原始操作。

Kanban（看板）——敏捷任务管理。

Image

3.6 架构与系统

Block Diagram（框图）——系统组件方框图。

Image

columns 定义网格列数。block:ID:列数 做分组。v11.15 新增 datastore shape（仅上下边框的矩形，适合数据流图）。

Quadrant Chart（象限图）——优先级矩阵，影响/可行性四象限。

Image

数据点 [x, y] 坐标范围 0-1。四象限自动分割。

Architecture Diagram（架构图）——云服务/基础设施架构，带图标。

Image

group 定义分组（可指定 icon：cloud/server/disk/database）。service 定义服务节点（同样可指定 icon）。L/R/T/B 表示连接端口方向。

3.7 知识组织

Mindmap（思维导图）——头脑风暴、知识梳理。

Image

缩进即层级，自动按圆心辐射布局。二级节点太多时 Mermaid 自动换角度排列。

04四、AI 时代的 Mermaid：LLM 原生输出

这是 Mermaid 最被低估的优势，也是拖拽工具永远追不上的护城河。

你对着 Claude 或 Cursor 说一句人话：

"画一个微服务电商系统的架构图，包含用户服务、商品服务、订单服务、支付服务、API 网关、消息队列、PostgreSQL、Redis，服务间通过 gRPC 通信，异步消息走 Kafka。"

它输出：

flowchart TB
    subgraph 客户端
        Web[Web 前端]
        App[移动端]
    end

    Gateway[API 网关 Kong]

    subgraph 业务服务
        UserSvc[用户服务<br/>gRPC]
        ProductSvc[商品服务<br/>gRPC]
        OrderSvc[订单服务<br/>gRPC]
        PaySvc[支付服务<br/>gRPC]
    end

    subgraph 中间件
        Kafka[Kafka 消息队列]
    end

    subgraph 数据层
        PG[(PostgreSQL)]
        Redis[(Redis)]
    end

    Web --> Gateway
    App --> Gateway
    Gateway --> UserSvc
    Gateway --> ProductSvc
    Gateway --> OrderSvc
    OrderSvc --> PaySvc
    OrderSvc --> Kafka
    PaySvc --> Kafka
    UserSvc --> PG
    ProductSvc --> PG
    OrderSvc --> PG
    UserSvc --> Redis
    ProductSvc --> Redis
Image

你把这段贴进文档——架构图出来了。改了需求？让 AI 再跑一次。重构了系统？改 prompt 就行。

Cursor 和 Copilot 对 .md 文件里的 Mermaid 代码块有补全支持——你写 flowchart，它帮你把节点和箭头续上。这是"用文本表达图表"的范式红利：当图表变成文本，它就天然进入了 LLM 的能力圈。

05五、踩坑与调优

用 Mermaid 两年，踩过的坑分享给你：

坑 1：中文不显示或显示为方块

默认字体可能不含中文字符。在图表第一行加 init 配置：

%%{init: {'themeVariables': {'fontFamily': 'Noto Sans SC, Microsoft YaHei, sans-serif'}}}%%
flowchart TD
    A[你好世界]

坑 2：复杂流程图排版不佳

节点超过 20 个时，默认的 dagre 布局可能生成"意大利面条"。两个解法：

  • 换方向：把 flowchart TD 改成 flowchart LR，横排有时比竖排更紧凑
  • 用 ELK layout：安装 @mermaid-js/layout-elk 插件，专业的自动布局算法（适合 30+ 节点）
  • 拆图：一张大图拆成 2-3 张小图 + subgraph 引用，既清楚又好维护

坑 3：暗色模式可读性

GitHub / VS Code 暗色模式下，默认主题的浅色背景会非常突兀。切换主题：

%%{init: {'theme': 'dark'}}%%
flowchart TD
    A[暗色适配]

可选主题：defaultneutraldarkforestbase。base 是最中庸的选择，深浅色背景下都能看——推荐给团队文档用。

坑 4：ER 图属性类型中文字段名

ER 图里中文字段名没问题，但字符 u（表示 unique）会与 v11 之前的版本冲突。升级到 v11.13+ 即可解决。

06六、完整示例：一个微服务系统的全套文档图

假设你在写一个电商系统的技术文档。下面两张图可以直接放进 README：

架构总览（Block Diagram）

：

flowchart TB
    subgraph 客户端
        Web[Web 前端]
        App[移动端]
    end
    Gateway[API 网关 Kong]
    subgraph 业务服务
        UserSvc[用户服务<br/>gRPC]
        ProductSvc[商品服务<br/>gRPC]
        OrderSvc[订单服务<br/>gRPC]
        PaySvc[支付服务<br/>gRPC]
    end
    subgraph 中间件
        Kafka[Kafka 消息队列]
    end
    subgraph 数据层
        PG[(PostgreSQL)]
        Redis[(Redis)]
    end
    Web --> Gateway
    App --> Gateway
    Gateway --> UserSvc
    Gateway --> ProductSvc
    Gateway --> OrderSvc
    OrderSvc --> PaySvc
    OrderSvc --> Kafka
    PaySvc --> Kafka
    UserSvc --> PG
    ProductSvc --> PG
    OrderSvc --> PG
    UserSvc --> Redis
    ProductSvc --> Redis
Image

下单时序：

sequenceDiagram
    participant U as 用户
    participant O as 订单服务
    participant P as 支付服务
    participant I as 库存服务
    participant N as 通知服务
    U->>O: 提交订单
    O->>I: 锁定库存
    I-->>O: 锁定成功
    O->>P: 创建支付单
    P-->>O: 支付链接
    O-->>U: 返回支付页面
    U->>P: 完成支付
    P->>O: 支付回调
    O->>I: 扣减库存
    O->>N: 发送通知
    N-->>U: 下单成功短信
    alt 库存不足
        I-->>O: 库存不足
        O-->>U: 下单失败
else 支付超时
        P->>O: 超时取消
        O->>I: 释放库存
        O-->>U: 订单已取消
    end
Image

07接下来怎么玩

在线 AI 生成：Mermaid Chart（https://mermaid.ai） 是官方出品的免费工具（部分功能付费），自然语言描述 → AI 生成 Mermaid 代码 → 在线编辑 → 导出/分享。适合非技术同事协作。（我们可以用 deepseek 或者 豆包生成代码后，复制过来渲染然后导出）

Image

CI/CD 集成：装 mermaid-cli（npm 包 @mermaid-js/mermaid-cli），

Image

在构建脚本里把 .mmd 文件批量转 SVG，自动嵌入文档站点：

npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.svg -t dark

结合 LangGraph：用 State Diagram 画 Agent 工作流的状态转移——每个节点是一个 Agent 或 Tool，转移线标注触发条件。Mermaid 是目前唯一能在代码仓库里直接渲染 Agent 架构图的方式。

回到开头那句话——你不用再为画图打开第三个工具了。Mermaid 让你的文档和图表住在同一个文件里，Git 记得每一次改动，AI 帮你写出第一版草稿。对于任何一个需要写技术文档的工程师，这是 2026 年最值得放进工具箱的技能之一。

本文全部 Mermaid 代码兼容 v11.15+。在线体验：mermaid.live

Image

KEEP THE THREAD GOING

更多来源文章