前言：程序员の画图之痛

作为一名程序员，你一定经历过这样的场景：

• 产品经理：「能不能画个流程图给我看看？」
• 你：打开 Visio，卡了
• 你：打开 Visual Paradigm，启动了 30 秒，License 过期了
• 你：打开 ProcessOn，要登录
• 你：打开 draw.io，画了半小时对齐箭头
• 你：「我用代码给你讲一遍吧...」

又或者：

• 写技术文档时，画了一张精美的架构图
• 需求变更，要加两个模块
• 重新打开源文件，发现是同事画的，用的 OmniGraffle
• 你用的 Windows
• 你：🙂

再或者：

• 用 Visual Paradigm 画了一套完整的 UML 图
• 换了台电脑，没有 License
• 导出成图片？改不了
• 导出成 XML？谁看得懂
• 你：🙂

如果画图能像写代码一样，用纯文本描述，Git 能 diff，改动能追溯，那该多好？

恭喜你，Mermaid 就是答案。

一、Mermaid 是什么？

Mermaid 是一个基于 JavaScript 的图表生成工具，让你用类似 Markdown 的纯文本语法来描述图表，然后自动渲染成 SVG 图形。

1.1 为什么说它最适合程序员？

1.2 AI 时代的杀手锏

这是 2024 年 Mermaid 最大的优势：AI 可以直接生成 Mermaid 代码。

试试对 ChatGPT / Claude 说：

「帮我画一个用户下单的时序图，包括用户、订单服务、库存服务、支付服务」

几秒钟后，一张完整的时序图就出来了。

对比传统工具：

这就是为什么说 Mermaid 是 AI 时代最适合程序员的图表工具——因为 AI 能理解它、生成它、修改它。

而 Visio、Draw.io 的二进制格式？AI 无能为力。

1.3 支持情况

基本上，程序员常用的文档工具都支持。

二、快速入门：5 种最常用的图表

2.1 流程图 (Flowchart) —— 最常用

语法要点：

graph TD           # TD=从上到下，LR=从左到右
    A[矩形]         # 普通节点
    B([圆角矩形])    # 开始/结束
    C{菱形}         # 判断
    D[(圆柱)]       # 数据库
    E[/平行四边形/]  # 输入/输出
    A --> B         # 箭头
    A -->|标签| B   # 带标签的箭头
    A --- B         # 无箭头连线
    A -.-> B        # 虚线箭头
    A ==> B         # 粗箭头

2.2 时序图 (Sequence Diagram) —— 接口交互必备

语法要点：

sequenceDiagram
    participant A as 别名     # 定义参与者
    A->>B: 同步请求          # 实线箭头
    B-->>A: 异步响应         # 虚线箭头
    A-xB: 丢失的消息         # 带 x 的箭头
    
    Note over A,B: 注释      # 跨参与者的注释
    
    alt 条件1               # 条件分支
        操作1
    else 条件2
        操作2
    end
    
    loop 循环条件            # 循环
        操作
    end
    
    opt 可选条件             # 可选
        操作
    end

2.3 类图 (Class Diagram) —— 面向对象设计

关系符号速查：

A <|-- B    继承（B 继承 A）
A *-- B     组合（A 包含 B，强依赖）
A o-- B     聚合（A 包含 B，弱依赖）
A --> B     关联
A ..> B     依赖
A <|.. B    实现接口

2.4 状态图 (State Diagram) —— 状态机必备

2.5 ER 图 (Entity Relationship Diagram) —— 数据库设计

关系符号：

||--||  一对一
||--o{  一对多
}|--|{  多对多

三、进阶图表

3.1 甘特图 (Gantt) —— 项目排期

3.2 饼图 (Pie Chart) —— 数据占比

3.3 Git 图 (Git Graph) —— Git 流程

3.4 思维导图 (Mindmap)

3.5 架构图示例：微服务支付系统

3.6 架构图

3.7 kanban

四、实用技巧

4.1 样式美化

样式属性：

fill        背景色
stroke      边框色
stroke-width 边框宽度
color       文字颜色

4.2 使用 FontAwesome 图标

4.3 添加链接

4.4 子图嵌套

五、踩坑指南：从入门到放弃的 N 个理由

经过大量实践，我总结了 Mermaid 让人想放弃的几个坑：

5.1 坑一：中文 ID 问题

错误写法：

graph LR
    subgraph 读取数据
        A[JSON]
    end
    style 读取数据 fill:#f00   # 报错！

正确写法：

graph LR
    subgraph read["读取数据"]
        A[JSON]
    end
    style read fill:#f00       # 正常！

规则：ID 用英文，显示文本用 ["中文"]

5.2 坑二：特殊字符转义

错误写法：

A[查询 user_id > 100 的数据]   # > 会被解析成箭头

正确写法：

A["查询 user_id > 100 的数据"]  # 用引号包裹

需要转义的字符： >, <, {, }, |, #

5.3 坑三：Subgraph 样式兼容性

部分渲染器不支持对 subgraph 使用 style：

# 可能不生效
style mySubgraph fill:#f00

替代方案：使用 CSS 类或接受默认样式

5.4 坑四：自引用循环

某些渲染器不支持：

subgraph A
    ...
end
A --> A   # 可能报错

替代方案：使用内部节点连接

subgraph A
    node1 --> node2
    node2 --> node1
end

5.5 坑五：渲染器差异

建议：以 GitHub 渲染结果为准，它的兼容性最好

5.6 坑六：版本兼容性地狱

这是最让人崩溃的坑：不同客户端内置的 Mermaid 版本不同，语法支持也不同。

各平台 Mermaid 版本参考（截至 2024 年）：

血泪教训：

# 你在 Mermaid Live Editor 写的（v10.6）
sankey-beta
    Agricultural 'waste',Bio-conversion,124.729

# 扔到 Confluence 一看
❌ Parse error: Unknown diagram type: sankey-beta

解决方案：

1. 确认目标平台版本：在写图之前，先确认你的目标平台支持哪个版本
2. 使用保守语法：如果要跨多平台使用，坚持用 flowchart、sequenceDiagram、classDiagram 这些经典图表
3. 查阅更新日志：https://github.com/mermaid-js/mermaid/releases
4. 本地预览时指定版本：Mermaid Live Editor 可以切换版本测试

5.7 调试工具推荐

1. Mermaid Live Editor: https://mermaid.live/

   • 实时预览
   • 错误提示清晰
   • 可导出 SVG/PNG

2. IntelliJ IDEA 插件: Mermaid

   • 插件市场搜索「Mermaid」安装
   • Markdown 文件内实时预览
   • 支持所有 JetBrains IDE（IDEA、WebStorm、PyCharm 等）
   • 配合 Markdown 插件使用体验更佳

3. VS Code 插件: Markdown Preview Mermaid Support

   • 本地预览
   • 语法高亮

六、最佳实践

6.1 文档规范

## 系统架构

下图展示了支付系统的整体架构：

​```mermaid
graph TB
    ...
​```

> 图 1：支付系统架构图

如图所示，系统分为三层...

6.2 复杂图表拆分

不要把所有内容塞进一张图：

6.3 命名约定

# 推荐
graph LR
    userService[用户服务]
    paymentDB[(支付数据库)]
    
# 不推荐
graph LR
    a[用户服务]
    b[(支付数据库)]

七、Mermaid vs 其他工具

7.1 工具定位象限图

7.2 同类产品详细对比

7.3 全面对比表

7.4 使用场景推荐

7.5 代码驱动工具语法对比

同一张时序图，不同工具的写法：

Mermaid:

sequenceDiagram
    Client->>Server: Request
    Server-->>Client: Response

PlantUML:

@startuml
Client -> Server: Request
Server --> Client: Response
@enduml

D2:

Client -> Server: Request
Server -> Client: Response

Mermaid 胜在 Markdown 原生支持，PlantUML 胜在 语法更丰富，D2 胜在 语法最简洁。

八、总结：什么时候该放弃？

说了这么多，Mermaid 确实不是万能的。

继续使用 Mermaid 当：

• 画技术文档中的流程图、时序图、架构图
• 需要版本控制和协作
• 追求效率而非极致美观
• 图表需要频繁修改
• 让 AI 帮你快速生成图表

考虑放弃 Mermaid 当：

• 需要高度定制化的视觉设计
• 给非技术人员看的宣传图
• 需要复杂的布局控制
• 图表元素超过 50 个（会很乱）
• 复杂的 ER 图和数据库设计（下面重点说）

8.1 Mermaid 的 ER 图：能用，但仅限于「能用」

Mermaid 的 erDiagram 语法简洁，画个简单的实体关系没问题：

但是，当你的数据库设计进入实战阶段，Mermaid 就歇菜了：

8.2 复杂 ER 图的正确打开方式：PDManer

如果你需要正经做数据库设计，推荐使用 PDManer（原 PDMan）：

PDManer 的 ER 图长这样：

┌─────────────────────────────────────────────┐
│ t_user                                       │
├─────────────────────────────────────────────┤
│ 🔑 id          BIGINT        主键           │
│    username    VARCHAR(50)   用户名 UK      │
│    email       VARCHAR(100)  邮箱           │
│    created_at  TIMESTAMP     创建时间       │
│ 📇 idx_email                 索引           │
└─────────────────────────────────────────────┘
          │
          │ 1:N
          ▼
┌─────────────────────────────────────────────┐
│ t_order                                      │
├─────────────────────────────────────────────┤
│ 🔑 id          BIGINT        主键           │
│ 🔗 user_id     BIGINT        用户ID FK      │
│    order_no    VARCHAR(32)   订单号 UK      │
│    amount      DECIMAL(12,2) 金额           │
└─────────────────────────────────────────────┘

然后一键生成：

• MySQL DDL
• PostgreSQL DDL
• Java Entity
• 数据字典文档

这才是数据库设计该有的样子。

8.3 决策流程图

一句话总结：

Mermaid 是技术文档的最佳拍档，但不是数据库设计的专业工具。

该用 Mermaid 时用 Mermaid，该用 PDManer 时别硬撑。

九、参考资源

Mermaid 相关：

• 官方文档: https://mermaid.js.org/
• 在线编辑器: https://mermaid.live/
• GitHub: https://github.com/mermaid-js/mermaid
• VS Code 插件: Markdown Preview Mermaid Support
• IDEA 插件: 插件市场搜索「Mermaid」

数据库设计工具：

• PDManer: https://gitee.com/robergroup/pdmaner （国产开源，推荐）

其他图表工具：

• PlantUML: https://plantuml.com/
• Draw.io: https://draw.io/
• Excalidraw: https://excalidraw.com/

后记

写完这篇文章，我用 Mermaid 画了 20+ 张图，没有打开任何绘图软件，全程在 Markdown 编辑器里完成。

这就是 Mermaid 的魅力：让画图回归写代码的感觉。

当然，它的坑也确实不少。但作为一个程序员，比起用鼠标拖拽对齐，我宁愿多背几个语法、多踩几个坑。

毕竟，能用代码解决的问题，就不要用鼠标。

这大概就是为什么我还没放弃 Mermaid 的原因吧。

——Joey，写于又一次被 Mermaid 渲染器坑了之后