Mermaid 权威使用指南：代码即图表的艺术与实践

摘要： Mermaid 是一款基于 JavaScript 的开源图表工具，采用“代码即图表”理念，通过文本定义动态生成图表，解决传统工具导致的“文档腐烂”问题。其核心优势包括易用性、版本控制友好性、广泛集成和可定制性，但在复杂布局控制上存在局限。Mermaid 生态系统包含开源库 Mermaid.js 和商业产品 Mermaid Chart，支持在线编辑器、IDE 插件及多平台集成。与其他工具（如

greenspan

248人浏览 · 2025-09-23 09:39:43

greenspan · 2025-09-23 09:39:43 发布

Mermaid 权威使用指南：代码即图表的艺术与实践

第一部分：Mermaid 简介——“代码即图表”的哲学

1.1 什么是 Mermaid？

从核心上讲，Mermaid 是一种基于 JavaScript 的图表绘制工具，它使用受 Markdown 启发的文本定义来动态生成和修改复杂的图表 1。该项目由 Knut Sveidqvist 于 2014 年创建，其初衷源于在文档工作流程中简化图表创建的需求，此前他深受专有软件格式和版本控制下维护图表困难之苦 3。

“文档腐烂”问题及其解决方案

Mermaid 的核心目标是解决所谓的“文档腐烂”（Doc-Rot）问题 1。这是一个棘手的困境：图表和文档的创建与更新非常耗时，导致它们很快就会与实际系统脱节，变得过时。而过时的文档不仅会损害团队的生产力，还会阻碍组织的知识传承 1。Mermaid 通过将图表视为代码来应对这一挑战。这种方法使得图表可以被轻松地修改、进行版本控制，甚至集成到开发脚本中，从而确保它们与其所描述的系统保持同步 1。

这种理念的根本优势在于可维护性，而不仅仅是创建的便捷性。传统的图表工具（如 Visio 或 Draw.io）通常生成二进制文件或复杂的 XML 文件。在 Git 等版本控制系统中，对这些文件进行差异比较（diff）极为困难。一个微小的视觉调整可能导致一个巨大且无法阅读的差异报告。这种高昂的更新成本使得开发人员在交付压力下，往往会忽略对相应图表的更新，这正是“文档腐烂”的根源。Mermaid 的解决方案是将图表的源文件变成简单、人类可读的文本。这种文本文件可以轻松地进行差异比较、在拉取请求（Pull Request）中进行审查，并像管理源代码一样进行管理。因此，Mermaid 的主要创新并非仅仅是将文本渲染成图像，而是从根本上改变了图表的生命周期，使其与现代软件开发实践保持一致。“代码即图表”（Diagrams as Code）的范式正是对这一维护难题的直接回应 8。

生态系统：Mermaid.js 与 Mermaid Chart

理解 Mermaid 生态系统的两个主要组成部分至关重要。Mermaid.js 是一个遵循 MIT 许可的开源 JavaScript 库，它提供了核心的图表渲染功能 3。而Mermaid Chart 是由 Mermaid.js 的创建者团队推出的商业产品，它提供了一个托管平台，具备可视化编辑器、实时协作、AI 驱动的图表生成以及企业级支持等高级功能 3。本指南将主要关注开源的 Mermaid.js，但也会在适当的时候提及 Mermaid Chart 提供的增强功能。

1.2 为何选择 Mermaid？一份比较分析

核心优势

简洁性与易用性：其受 Markdown 启发的语法学习曲线平缓，使得无论是开发人员还是非技术人员都能轻松上手 4。
版本控制与协作：作为纯文本文件，Mermaid 图表非常适合与 Git 等版本控制系统集成，从而实现清晰的版本历史记录，并通过拉取请求进行协作审查 7。
广泛的集成：Mermaid 拥有一个庞大的生态系统，支持在各种集成开发环境（IDE）、文档平台和维基系统中直接使用，使图表能够紧邻其描述的代码或文本 2。
高度可定制：用户可以使用类似 CSS 的语法、主题和配置选项来定义图表的样式，从而保持视觉上的一致性 4。

社区视角与公认的不足

尽管 Mermaid 功能强大，但社区也指出了其存在的一些挑战。有时，其工具链会给人一种尚未成熟或仍处于“测试阶段”的感觉，偶尔还会出现破坏性的变更 17。一个反复被提及的重要批评是，精确控制图表布局非常困难。Mermaid 的布局引擎可能显得有些“混乱”，文本的微小改动有时会导致整个图表布局发生剧烈变化。相比之下，PlantUML 等工具提供了更精细的控制 9。这使得 Mermaid 成为快速原型设计的绝佳工具，但对于那些布局本身就是关键信息的复杂图表而言，它可能不是最佳选择 17。

与其他工具的比较

vs. PlantUML：PlantUML 是一款历史更悠久、更成熟的工具，支持更广泛的 UML 图表类型，并提供更精确的布局控制。然而，Mermaid 作为原生 JavaScript 库，更容易集成到基于 Web 的平台中，并且其语法通常被认为更简洁 9。
vs. Graphviz：Graphviz 是一款强大的图形可视化工具，已经存在了数十年。Mermaid 在某种程度上可以被看作是 Graphviz 概念的 JavaScript 实现，但更侧重于 Web 原生渲染和更易于上手的语法 17。
vs. 所见即所得（WYSIWYG）工具 (例如 Draw.io)：WYSIWYG 编辑器提供了完全的视觉控制，对非编码人员非常直观。但它们的弱点在于难以进行版本控制，并且难以通过编程方式来维护图表的一致性和进行更新，而这恰恰是 Mermaid 的核心优势 11。

Mermaid 在简洁性与功能性之间找到了一个“最佳平衡点”，但这是以牺牲部分布局控制为代价的。其设计哲学优先考虑的是将布局的复杂性从用户那里抽象出来。用户只需定义实体间的关系（例如，“A 连接到 B”），渲染引擎则负责决定其呈现方式。这是一种深思熟虑的权衡，它降低了入门门槛，并加快了中低复杂度图表的创建速度，从而实现了快速文档化的目标。然而，对于高度复杂的系统架构图，精确的布局本身往往是所要传达信息的一部分。当自动布局引擎做出不理想的选择时，用户几乎没有调整的余地，这可能会导致挫败感。最近引入的 ELK 布局引擎正是对这一局限性的承认，并试图提供更复杂、更可控的布局选项 9。因此，用户应当对 Mermaid 抱有现实的期望：它非常适合满足 80% 的文档需求（如流程图、序列图、实体关系图），在这些场景中，内容比像素级的精确布局更为重要。

第二部分：Mermaid 生态系统入门

本部分将提供可操作的、分步的指南，介绍用户可以立即开始创建图表的各种方式，以满足不同的偏好和使用场景。

2.1 即时体验：Mermaid 在线编辑器

Mermaid 在线编辑器（Mermaid Live Editor）是无需任何安装即可开始体验 Mermaid 的最快方式 3。这是一个位于mermaid.live 的在线工具 19。

编辑器界面详解

该编辑器通常采用多面板布局，旨在提供无缝的“代码到图像”体验 11：

代码面板：用于编写类似 Markdown 的 Mermaid 语法。该面板提供语法高亮、自动补全和实时错误提示等功能，极大地提升了编写效率 11。
预览面板：在您输入代码时实时渲染出图表，让您能够即时看到修改的效果 11。
配置面板：允许用户自定义主题、字体、颜色和其他渲染选项，以调整图表的最终外观 11。
历史记录面板：自动保存代码的版本，用户可以追踪变更并根据需要回滚到之前的版本 11。

用户可以从大量的示例图表中选择一个作为起点，通过唯一的 URL 链接分享图表，并将最终的视觉成果导出为 SVG 或 PNG 格式的文件 7。

2.2 本地开发：IDE 与文本编辑器

Visual Studio Code

对于许多开发人员来说，VS Code 是主要的工作环境。官方的 Mermaid Chart VS Code 插件以及其他社区插件提供了丰富的图表编辑体验 11。

核心功能：插件提供实时预览窗格、针对 .mmd 文件和 Markdown 文件内嵌代码块的语法高亮、平移和缩放、错误高亮，并支持与 Mermaid Chart 账户集成以实现云同步 21。
AI 集成：Mermaid Chart 插件允许通过 GitHub Copilot Chat 直接从源代码生成图表。例如，用户可以输入 @mermaid-chart “根据此 API 调用流程创建一个序列图” 来自动生成图表 21。微软也推出了一个名为
vscode-mermAId 的实验性扩展，同样用于 Copilot 驱动的图表生成 23。

Obsidian

对于知识管理和笔记记录，Obsidian 内置了对 Mermaid 的核心支持，使其成为在笔记中嵌入动态图表的理想工具 17。

使用方法：只需在笔记中创建一个 ````mermaid` 代码块即可。请确保在设置中启用了核心的 Mermaid 插件 24。
社区插件：可以通过安装社区插件来增强体验，例如“Mermaid Tools”插件可以添加一个可视化工具栏，用于插入语法元素；“Mermaid Themes”插件则提供了更好的样式支持 25。

2.3 Web 集成：从 CDN 到 NPM

使用 CDN 简单嵌入

在静态网站上使用 Mermaid 最直接的方法是通过内容分发网络（CDN）如 jsDelivr 或 cdnjs 引入其库文件 1。

实现步骤：
1. 在 HTML 文件的 <script> 标签中引入 Mermaid ESM 模块 1。
2. 将您的 Mermaid 语法代码放置在 <pre class=“mermaid”> 或 <div class=“mermaid”> 标签内 1。
3. 调用 mermaid.initialize({ startOnLoad: true });，这会使 Mermaid 在页面加载时自动查找并渲染所有此类代码块 1。

作为项目依赖集成

对于现代 Web 应用程序（如使用 React、Vue 等框架），应通过包管理器将 Mermaid 安装为项目依赖项 4。

安装命令：npm install mermaid 或 yarn add mermaid 11。
使用方法：在您的应用中导入该库，并使用 Mermaid API 以编程方式渲染图表。mermaid.render() 函数接收一个图表定义字符串并返回 SVG，从而允许在应用程序中动态生成视觉效果 11。

2.4 平台集成：在您的工作流中使用 Mermaid

GitHub 和 GitLab

GitHub 和 GitLab 都为 Mermaid 图表提供了原生支持，用户可以直接在 Markdown 文件、问题（Issues）、拉取请求和维基页面中使用 6。

语法：使用带有 mermaid 语言标识符的代码块：mermaid… 31。

其他平台

许多其他工具也支持 Mermaid，包括 Confluence（通过插件）、Notion 以及各种静态网站生成器，如 Hugo 和 MkDocs 7。

Mermaid 代码的“可移植性”是一项关键的战略优势。同一段 Mermaid 代码可以在在线编辑器中渲染，在 VS Code 中预览，在 GitHub 的 README 文件中显示，在 Obsidian 笔记中嵌入，也可以在一个自定义网页上运行。这种代码本身成为一种可移植、自包含的文档工件的能力，极大地减少了重复工作，并确保了在不同上下文（原型设计、开发、正式文档、个人笔记）中的一致性。与特定工具的图表格式相比，这是一个显著的优势。

第三部分：精通语法——深入解析各类图表

这是本指南的核心参考部分。每个小节都将提供完整的语法分解、从简单到复杂的多个带注释的示例，以及最佳实践。

3.1 流程图：可视化流程与逻辑

流程图用于表示工作流或过程，展示步骤和决策点。

声明：以 flowchart 或 graph 关键字开始，后跟一个方向标识符，如 TB/TD（从上到下）、BT（从下到上）、LR（从左到右）或 RL（从右到左）11。
节点：通过一个唯一的 ID 定义，该 ID 必须是无空格的单个词。可以使用不同样式的括号为节点添加描述性标签，这些括号同时也定义了节点的形状 11。例如：
nodeId[这是标签]。
节点形状：Mermaid 支持多种多样的节点形状，通过不同的包裹字符来定义。下表是一个全面的速查表，极大地提高了可用性。

形状名称	语法示例	描述/用例
矩形 (默认)	id[文本]	表示流程中的一个步骤或操作。
圆角矩形	id(文本)	通常用于表示流程的开始或结束。
体育场形	id([文本])	另一种表示开始/结束或特定过程的形状。
子程序形	id[[文本]]	表示一个预定义的过程或子程序。
圆柱形	id[(文本)]	代表数据库或数据存储。
圆形	id((文本))	表示一个连接点或事件。
菱形	id{文本}	用于表示决策点，通常有多个输出路径。
六边形	id{{文本}}	用于表示准备步骤或初始化操作。
平行四边形	id[/文本/]	表示输入或输出数据。
梯形	id[/文本\]	表示手动操作。

链接 (边)：定义节点之间的连接。支持不同的箭头样式和线条类型，并可以为链接添加文本 11。
- 带箭头的链接：A --> B
- 无箭头的链接：A — B
- 虚线链接：A -.- B
- 粗线链接：A ==> B
- 带文本的链接：A – 这是文本 --> B 或 A -->|文本| B

子图：使用 subgraph 和 end 关键字将相关节点分组，以管理复杂性。可以在不同子图的节点之间或与子图本身建立链接 11。

示例：

flowchart LR
 subgraph "数据处理"
     A[数据输入] --> B{数据验证}
 end
 subgraph "数据存储"
     C[(数据库)]
 end
 B -->|有效| C
 B -->|无效| D[丢弃]

3.2 序列图：描绘时序交互

序列图用于展示对象之间如何以及以何种顺序进行交互。

声明：以 sequenceDiagram 关键字开始 1。
参与者与角色：定义垂直的生命线。participant 创建一个矩形框，actor 创建一个小人图标。可以使用别名来简化代码 1。例如：
participant 用户 as U。
消息：表示通信。语法包括源、箭头类型、目标和可选的消息文本 37。
- 同步消息：A->>B: 请求
- 异步消息：A-)B: 事件通知
- 回复消息：B–>>A: 响应
- 不同的线条（-> vs -->）和箭头（>>, x, )）表示不同的消息类型 37。
激活：显示参与者何时处于活动（处理）状态。可以使用 activate 和 deactivate 关键字显式控制，也可以通过在消息箭头后附加 + 和 - 来隐式控制 37。
复杂流程控制：这些结构对于模拟真实世界的逻辑至关重要。
- 循环：使用 loop [描述]… end 来表示重复的操作 37。
- 选择 (If/Else)：使用 alt [条件A]… else… end 来表示条件分支 37。
- 可选：使用 opt [描述]… end 来表示可选的序列 37。
- 并行：使用 par [动作1]… and [动作2]… end 来表示并发执行的动作 37。
注释与分组：使用 Note right of A: 文本添加解释性注释，使用 box “分组名”… end 对参与者进行分组 37。
- 示例：

sequenceDiagram
    autonumber
    actor User
    participant WebServer
    participant Database

    User->>+WebServer: POST /login
    WebServer->>+Database: SELECT user WHERE name=?
    Database-->>-WebServer: User record
    alt 凭证有效
        WebServer-->>-User: 200 OK
    else 凭证无效
        WebServer-->>-User: 401 Unauthorized
    end

3.3 类图：建模面向对象结构

类图是面向对象建模的基石，用于描述系统的静态结构。

声明：以 classDiagram 关键字开始 1。
定义类：可以通过 class 关键字显式定义，也可以通过关系定义隐式创建。一个类包含三个部分：名称、属性和方法 42。
定义成员（属性和方法）：
- 语法：[可见性]类型名称用于属性，[可见性]方法名(参数) 返回类型用于方法 41。
- 可见性符号：+ (public), - (private), # (protected), ~ (package/internal) 43。
- 静态成员使用 $ 标记，抽象成员使用 * 标记 42。
- 泛型使用波浪线 ~ 包裹：List~T~ 41。
关系：类之间的连接至关重要。下表是一个关系速查表，对于开发者来说非常有价值。

关系类型	Mermaid 语法	UML 符号	描述
继承/泛化	`<	–`	héritage
组合	*–	◆–	强“拥有”关系，部分与整体共存亡 (has-a 关系)。
聚合	o–	◇–	弱“拥有”关系，部分可以独立于整体存在 (has-a 关系)。
关联	–>	–>	表示类之间的一般关系。
依赖	…>	…>	表示一个类依赖于另一个类的定义或实现。
实现	`…	>`	…

基数与标签：可以为关系添加多重性（如 “1”, “0…*”）和描述性标签 41。例如：
Customer “1” – “0…*” Order : places。
- 示例：

classDiagram
    class Animal {
        +String name
        +eat()
    }
    class Dog {
        +bark()
    }
    class Cat {
        +meow()
    }
    Animal <|-- Dog
    Animal <|-- Cat

3.4 甘特图：项目调度与管理

甘特图是项目管理中用于展示任务、时间和依赖关系的条形图。

声明：以 gantt 关键字开始 1。
配置：关键设置包括 title（标题）、dateFormat（日期格式，如 YYYY-MM-DD）和 axisFormat（坐标轴格式）1。
结构：图表通过 section 块来组织相关的任务 44。
定义任务：任务由其名称、状态、ID、开始日期/依赖项和持续时间/结束日期定义 44。
- 语法：任务名称 :[状态], [id], [开始时间], [持续时间]
- 状态可以是 done（已完成）、active（进行中）或 crit（关键任务）45。
- 可以使用 after [id] 来设置依赖关系 44。
里程碑：表示持续时间为零的关键事件，使用 milestone 关键字定义 45。
- 示例：

gantt
    title 项目开发计划
    dateFormat YYYY-MM-DD
    section 设计阶段
    需求分析 :done, des1, 2024-01-01, 7d
    UI/UX 设计 :active, des2, after des1, 10d
    section 开发阶段
    前端开发 :des3, after des2, 20d
    后端开发 :des4, after des2, 25d

3.5 实体关系图 (ERD)：数据库设计

ER 图用于可视化数据库的结构，包括实体、属性和它们之间的关系。

声明：以 erDiagram 关键字开始 1。
实体与属性：在花括号 {} 内定义实体（表）及其属性（列）。属性由类型和名称组成，可以指定主键（PK）和外键（FK）47。
- 示例：CUSTOMER { int id PK; string name } 49。
关系与基数：Mermaid 使用“鸦爪”表示法来定义实体间的关系和基数 47。

含义	符号	Mermaid 语法
零或一	⚬	`o
仅一个
零或多个	⚬{	o{
一个或多个		{

识别与非识别关系：实线 (–) 表示识别关系（子实体不能脱离父实体存在），而虚线 (…) 表示非识别关系 47。
- 示例：

erDiagram
    CUSTOMER |
    |--|{ ORDER : "places"
ORDER |
|--|{ LINE-ITEM : "contains"
CUSTOMER {
int id PK
string name
string email
}
ORDER {
int id PK
int customer_id FK
datetime order_date
}

3.6 其他图表类型概览

状态图：用于建模系统行为。以 stateDiagram-v2 开始，定义状态、转换 (–>)、起点/终点 ([*])、复合状态和并发 (–) 50。
饼图：用于可视化比例。以 pie 开始，可以包含 title，并使用简单的 “标签” : 数值语法 6。
Git 图：用于可视化 Git 分支历史。以 gitGraph 开始，使用 commit、branch、checkout 和 merge 等命令 1。

第四部分：高级定制与主题化

本部分将超越语法，探讨图表的美学和配置，帮助用户创建专业且一致的视觉效果。

4.1 宏观样式：主题、布局与外观

应用主题：Mermaid 提供了多个内置主题（default, dark, forest, neutral, base），可用于改变整体配色方案 32。其中
base 主题专为自定义而设计 55。
使用 Frontmatter 进行配置：为单个图表进行配置的主要方法是在代码顶部使用由 — 包裹的 YAML 块 9。这允许设置主题、布局选项和其他参数。
- 示例：

---
config:
  theme: 'dark'
---
graph TD
    A --> B

布局引擎与视觉“外观”：为了解决布局方面的批评，Mermaid 引入了新的选项，目前主要支持流程图和状态图 18。
- 布局引擎：用户可以将默认的 dagre 引擎切换到更先进的 elk 引擎，以获得可能更优的图表排列 (layout: elk) 9。
- 外观 (Looks)：通过 look 参数可以改变图表的整体美学风格。选项包括 classic（原始风格）、handDrawn（手绘草图效果）和 neo（现代风格）18。

4.2 使用 classDef 和 CSS 进行精细控制

定义样式类：classDef 语句是在图表内部创建可复用 CSS 样式集的最强大方式。这对于为不同类型的节点（例如，所有数据库节点都为蓝色）维护一致的视觉语言至关重要 7。
- 语法：classDef className fill:#f9f,stroke:#333,stroke-width:4px 7。
应用样式类：定义好的类可以应用于一个或多个节点。
- 使用 ::: 操作符应用于单个节点：nodeId[标签]:::className 9。
- 使用 class 语句应用于多个节点：class nodeId1,nodeId2 className 7。
直接样式与链接样式：对于一次性的样式，可以使用 style 关键字：style nodeId fill:#f9f。对于链接，可以使用 linkStyle：linkStyle 0 stroke-width:2px,stroke:red;（其中 0 是链接的索引）7。

样式优先级层次结构

Mermaid 提供了多种应用样式的方式，包括全局 initialize() 调用、frontmatter config、classDef、内联 style 以及外部 CSS 9。理解它们的优先级对于调试样式至关重要。一个清晰的优先级模型是：

外部 CSS > 内联 style > classDef > Frontmatter 配置 > 全局 initialize() 主题。例如，一个内联 style 会覆盖应用于同一节点的 classDef 样式。而 classDef 又会覆盖通过 frontmatter 设置的主题默认值。这个层次结构为用户提供了一个解决“为什么我的样式没有生效？”这类常见问题的心理模型，因为它清晰地展示了哪条规则正在覆盖另一条。

第五部分：最佳实践与未来展望

本部分提供实用建议，并探讨 Mermaid 在技术行业中的更广泛背景和未来发展。

5.1 高效图表绘制的实用建议

保持清晰与简洁：让每个图表专注于一个单一的目的，避免信息过载。使用子图来管理复杂性，并用注释来解释不明显的部分 9。
注重可维护性：为节点使用有意义的 ID。利用 classDef 为您的图表创建一致且易于更新的样式指南。像对待应用程序代码一样，认真对待您的图表代码。
善用生态系统：对于快速原型设计和分享，使用在线编辑器 7。对于涉及非技术利益相关者的团队项目，Mermaid Chart 的可视化编辑器和协作功能可以改变游戏规则 12。利用 AI 功能从现有代码或自然语言提示中引导生成复杂图表，然后手动优化其语法 12。

5.2 基于文本的图表绘制技术的发展趋势

应对批评与持续演进

社区对于语法脆弱和布局控制混乱的反馈是真实存在的 17。Mermaid 团队正在积极应对这些问题，其持续的开发工作，如引入 ELK 布局引擎和新的节点形状语法，正是为了解决这些痛点 9。

未来是混合模式

Mermaid Chart 推出的可与底层代码同步的可视化编辑器，预示着一个未来趋势：代码与图形用户界面（GUI）之间的界限将变得模糊 12。这种混合方法能够适应不同用户的偏好和技能水平，让“代码即图表”的范式被更广泛的受众所接受 13。

结论

Mermaid 作为一个屡获殊荣的工具，已经成功地解决了技术文档领域的一个关键痛点 2。它通过将图表转化为可版本控制的文本，极大地提高了技术文档的维护效率和协作能力。尽管在布局控制等方面仍有改进空间，但其活跃的社区、不断增长的生态系统和持续扩展的功能集表明，它将在未来很长一段时间内继续作为“代码即图表”运动的基石。无论是用于快速原型设计、嵌入代码仓库的文档，还是用于复杂的系统建模，Mermaid 都提供了一种强大、灵活且高效的解决方案。