作为一个技术人员，我们往往更擅长写代码，而不是做设计。但无论是写技术文档、做架构设计，还是给老板汇报进度，图表（Diagrams） 又是必不可少的。
以前我总是在 Visio 或者 PPT 里痛苦地拖拽方框、对齐线条。一旦需求变更（比如流程里加了一个判断条件），整张图就得重新排版，简直是噩梦。
直到我开始深度使用 Mermaid，这种“Diagrams as Code”（像代码一样管理图表）的方式，彻底治愈了我的“画图焦虑症”。
今天这就给大家整理一份 Mermaid 的核心用法，以及我平时常用的一些调试技巧。
什么是 Mermaid？
简单来说，Mermaid 是一个基于 JavaScript 的图表绘制工具。它允许你使用类似 Markdown 的文本语法来定义图表，然后自动渲染成图片。
它的核心优势在于：
- 版本控制：图表是文本，可以存入 Git，谁改了什么一目了然。
- 自动布局：你只负责逻辑（A 指向 B），它负责排版（不用纠结线条歪没歪）。
- 多处集成：GitLab、Notion、Obsidian 甚至 GitHub 原生都支持。
核心实战：三类最常用的图
1. 流程图 (Flowchart)
这是最基础的。TD 代表 Top-Down（从上到下），LR 代表 Left-Right（从左到右）。
graph TD
A[开始] --> B{是否已登录?}
B -- 是 --> C[进入首页]
B -- 否 --> D[跳转登录页]
D --> B
C --> E[结束]
渲染效果：
graph TD
A[开始] --> B{是否已登录?}
B -- 是 --> C[进入首页]
B -- 否 --> D[跳转登录页]
D --> B
C --> E[结束]
代码解析：
[]表示矩形，{}表示菱形。-->表示箭头。- 中间的文字直接写在连线上即可。
2. 时序图 (Sequence Diagram)
写后端接口文档或者分析交互逻辑时的神器。
sequenceDiagram
participant U as 用户
participant S as 服务器
participant D as 数据库
U->>S: 发起请求 (Login)
S->>D: 查询用户信息
D-->>S: 返回数据
alt 验证成功
S->>U: 返回 Token
else 验证失败
S->>U: 返回 401 错误
end
渲染效果：
sequenceDiagram
participant U as 用户
participant S as 服务器
participant D as 数据库
U->>S: 发起请求 (Login)
S->>D: 查询用户信息
D-->>S: 返回数据
alt 验证成功
S->>U: 返回 Token
else 验证失败
S->>U: 返回 401 错误
end
代码解析：
->>实线箭头，-->>虚线箭头。alt ... else ... end用来表示逻辑分支。
3. 甘特图 (Gantt)
项目排期不用 Excel，用代码写反而更直观。
gantt
title 项目开发计划
dateFormat YYYY-MM-DD
section 后端开发
需求分析 :a1, 2026-01-01, 3d
API设计 :after a1, 2d
section 前端开发
页面切图 :2026-01-03, 4d
联调 : 2d
渲染效果：
gantt
title 项目开发计划
dateFormat YYYY-MM-DD
section 后端开发
需求分析 :a1, 2026-01-01, 3d
API设计 :after a1, 2d
section 前端开发
页面切图 :2026-01-03, 4d
联调 : 2d
高效编写与调试技巧
虽然 Mermaid 语法很简单，但在实际编写复杂的架构图时，如果是盲写（Blind Coding），很容易因为缺了一个括号导致渲染失败。
通常我们有几种编写环境：
- IDE 插件：在 VS Code 中安装 Mermaid 插件，可以边写边看。
- Notion/Obsidian：直接在笔记软件里写。
- 在线编辑器：这是我非常推荐的一种方式，特别是当你没有打开 IDE，或者需要快速验证一段代码逻辑发给同事时。
市面上有很多在线工具，但我个人比较喜欢用这个 免费Mermaid编辑器。
推荐理由主要有两点：
- 所见即所得：左边写代码，右边毫秒级实时渲染。对于新手来说，能立刻看到
-->和-.->的区别非常重要。 - 纯净轻量：打开浏览器就能用，不需要登录注册，也没有乱七八糟的广告干扰。
- 内置模板：内置有多种常用的模板。
比如有时候我在写技术文档，需要插入一张图，我会先在这个编辑器里把逻辑理顺，图画好，然后直接点击复制 SVG 或者代码，粘贴到我的 Markdown 文档里，效率极高。
进阶：如何让图更好看？
默认的 Mermaid 样式比较朴素，其实它是支持自定义样式的。
比如，你想把重点节点标记为红色：
graph LR
A[普通节点] --> B[危险操作]
style B fill:#f9f,stroke:#333,stroke-width:4px
渲染效果：
graph LR
A[普通节点] --> B[危险操作]
style B fill:#f9f,stroke:#333,stroke-width:4px
你只需要在代码末尾加上 style 节点ID 样式属性 即可。如果你对 CSS 有所了解，这里的属性基本是通用的。建议在上面提到的在线编辑器里多尝试几种配色，找到适合你项目文档风格的配色方案。
总结
作为开发者，“Everything as Code” 是一种信仰。Mermaid 让我们从繁琐的 UI 调整中解放出来，回归到梳理逻辑本身。
如果你还在忍受 Word 或 Visio 的排版折磨，不妨花 10 分钟试试 Mermaid。配合一个顺手的实时预览工具，你会发现，画图其实和写代码一样，充满逻辑之美。
