【保姆级教程】Mermaid 语法从入门到精通，彻底告别鼠标拖拽

用户299142219680
78 阅读5分钟

作为一名技术人员（或者产品经理/文档编写者），你是否经历过这样的崩溃时刻：

为了画一张架构图或流程图，在 Visio 或 在线画图网站 里拖拽半天，为了对齐两个方框的像素眼都花了；好不容易画好了，需求变更了，又得重新拖拽调整连线；最头疼的是，图表无法进行版本控制，放入 Git 仓库里只是一个二进制文件，谁改了什么完全不知道。

如果你有同感，那么 "Diagram as Code"（像写代码一样画图） 的理念就是为你准备的，而 Mermaid 正是这一领域的王者。

今天这篇文章，就带大家详细拆解 Mermaid 的核心用法，并分享一些提升效率的实用工具。

什么是 Mermaid？

Mermaid 是一个基于 JavaScript 的图表绘制工具。它允许你使用类似 Markdown 的简单文本语法来定义图表，然后由浏览器自动渲染成复杂的图形。

为什么要用它？

  1. 文本即图表：纯文本存储，体积小，不仅便于阅读，更完美支持 Git 版本管理。
  2. 自动布局：你只需要关心“节点 A 指向 节点 B”，具体的连线路径、对齐方式由引擎自动搞定，告别“像素眼”。
  3. 生态丰富：GitHub、GitLab、Notion、Obsidian、VS Code 等主流工具原生支持。

Mermaid 核心图表实战

Mermaid 支持几十种图表，这里我们只讲最高频使用的三种，学会了能解决 90% 的工作需求。

1. 流程图 (Flowchart)

这是最基础的图表，用于描述系统逻辑或业务流程。

代码示例：

graph TD
    A[开始] --> B{是否有Bug?}
    B -- 是 --> C[修复Bug]
    C --> D[提交代码]
    B -- 否 --> D
    D --> E[发布上线]
    E --> F((结束))

语法解析：

  • graph TD：表示从上到下（Top-Down）的图。如果是从左到右，就用 graph LR。
  • -->：表示箭头指向。
  • []、{}、(())：分别代表矩形、菱形判断、圆形节点。

渲染效果：

graph TD
    A[开始] --> B{是否有Bug?}
    B -- 是 --> C[修复Bug]
    C --> D[提交代码]
    B -- 否 --> D
    D --> E[发布上线]
    E --> F((结束))

2. 时序图 (Sequence Diagram)

后端开发和架构师的最爱，用于展示对象之间的交互顺序。

代码示例：

sequenceDiagram
    participant U as 用户
    participant S as 服务器
    participant D as 数据库

    U->>S: 发起登录请求
    Note right of U: 密码已加密
    S->>D: 查询用户信息
    D-->>S: 返回用户数据
    alt 验证成功
        S-->>U: 返回 Token
    else 验证失败
        S-->>U: 返回错误提示
    end

语法解析：

  • participant：定义参与者。
  • ->>：实线箭头（请求）。
  • -->>：虚线箭头（响应）。
  • alt ... else ... end：用来表示条件分支（比如成功或失败的情况）。

渲染效果：

sequenceDiagram
    participant U as 用户
    participant S as 服务器
    participant D as 数据库

    U->>S: 发起登录请求
    Note right of U: 密码已加密
    S->>D: 查询用户信息
    D-->>S: 返回用户数据
    alt 验证成功
        S-->>U: 返回 Token
    else 验证失败
        S-->>U: 返回错误提示
    end

3. 甘特图 (Gantt)

项目经理的神器，用来展示项目进度。

代码示例：

gantt
    title 项目开发计划表
    dateFormat  YYYY-MM-DD
    section 需求阶段
    需求分析       :a1, 2025-10-01, 5d
    原型设计       :after a1, 3d
    section 开发阶段
    后端架构       :2025-10-10, 5d
    前端页面       :2025-10-12, 5d

渲染效果：

gantt
    title 项目开发计划表
    dateFormat  YYYY-MM-DD
    section 需求阶段
    需求分析       :a1, 2025-10-01, 5d
    原型设计       :after a1, 3d
    section 开发阶段
    后端架构       :2025-10-10, 5d
    前端页面       :2025-10-12, 5d

如何高效编写与预览？（含工具推荐）

学会了语法，在哪里写是个问题。通常我们有几种选择：

  1. IDE 插件：在 VS Code 中安装 Mermaid Preview 插件。优点是离代码近，缺点是由于环境配置问题，有时候预览渲染比较慢，或者导出图片比较麻烦。
  2. 笔记软件：在 Notion 或 Obsidian 中直接写。优点是文档一体化，缺点是不方便分享纯图给没有账号的同事。
  3. 在线编辑器：这是最推荐的方式，尤其是当你需要快速验证一段代码，或者需要生成高清 SVG/PNG 图片插入到 Word/PPT 时。

市面上的在线编辑器很多，官方的 Live Editor 功能虽然全但国内访问速度有时不稳定。最近我在用一个非常轻量且干净的在线工具，体验很不错：

👉 Mermaid Editor 在线编辑器： tools.ai225.com/tools/merma…

这个工具的几个好用的点：

  • 实时渲染极快：左边写代码，右边秒出图，几乎没有延迟。
  • 界面清爽无广：打开就是干活的界面，没有乱七八糟的干扰。
  • 导出方便：写完之后，直接一键导出 SVG 或 PNG，清晰度很高，非常适合贴到技术文档里。
  • 示例丰富：如果你忘记了语法，它里面内置了不少模板（Examples），点一下就能直接在基础上修改，不用去死记硬背语法。

建议大家可以把这个链接收藏到书签栏，平时写文档或者做 PPT 需要插图时，打开就能用，比打开笨重的 Visio 快多了。

进阶技巧：让你的图表更专业

  • 使用子图（Subgraph）：在流程图中，可以用 subgraph 将相关的节点包裹起来，体现模块化思想。
  • 自定义样式：Mermaid 允许使用 style 或 classDef 来给特定的节点上色。例如：style A fill:#f9f,stroke:#333,stroke-width:4px。
  • 结合 AI：现在的 ChatGPT 或 Claude 都非常擅长写 Mermaid。你可以直接对 AI 说：“帮我生成一个用户登录的 Mermaid 时序图”，然后把代码复制到上面提到的 Mermaid 编辑器 中进行微调和导出，效率直接起飞。

总结

Mermaid 改变了我们记录思维的方式。它让图表变成了“代码”，让维护文档不再是噩梦。

无论你是刚入门的开发者，还是资深的架构师，掌握 Mermaid 都是一项高回报的技能。哪怕你现在还没完全背过语法，也可以先利用好在线编辑器和 AI 工具，先让工作流“转”起来。

最后，别忘了去试试上面提到的编辑器，真的能省不少事儿！

avatar
文章
阅读
粉丝