Mermaid 常用用法教程

张剑龙

667人浏览 · 2026-03-10 19:36:41

张剑龙 · 2026-03-10 19:36:41 发布

文章目录

前言

Mermaid 是一个基于 JavaScript 的图表绘制工具，用类似 Markdown 的文本语法就能创建各种图表。下面从基础到进阶，系统介绍常用用法。

一、安装与使用

在线使用

· 官方在线编辑器： mermaid.live
· Markdown 编辑器：Typora、Obsidian、Notion（部分支持）
· GitHub：支持 .mmd 文件或 Markdown 代码块

本地安装

# 使用 npm 安装
npm install -g @mermaid-js/mermaid-cli

# 在 HTML 中引入
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>

二、流程图 (Flowchart)

基础语法

我们可以直接在 markdown 中用 Mermaid 语法，只需要用下面包裹内容

    ```mermaid
    ...你的流程图内容
    ```

graph TD
    A[开始] --> B{判断条件}
    B -->|是| C[处理1]
    B -->|否| D[处理2]
    C --> E[结束]
    D --> E

语法要点：

graph TD：从上到下（TB/TD 也同上到下，LR 从左到右，RL 从右到左，BT 从下到上）
A[文本]：方形节点
A(文本)：圆角节点
A{文本}：菱形节点（判断）
A((文本))：圆形节点
A --> B：箭头连接
A --- B：无箭头连接
A -- 注释 --> B：带文字连接
A -->|是| B：另一种带文字连接

节点样式

graph LR
    A[方形节点]
    B(圆角节点)
    C{菱形节点}
    D((圆形节点))
    E>不对称节点]
    F[[子程序节点]]
    
    A --> B --> C --> D --> E --> F

子图

graph TB
    subgraph 子图1
        A1-->A2
    end
    subgraph 子图2
        B1-->B2
    end
    A2-->B1

三、时序图 (Sequence Diagram)

基础语法

sequenceDiagram
    participant 用户
    participant 前端
    participant 后端
    
    用户->>前端: 点击按钮
    前端->>后端: API请求
    后端-->>前端: 返回数据
    前端-->>用户: 显示结果

语法要点：

· participant：定义参与者
· ->>：实线箭头
· -->>：虚线箭头
· -)：异步消息
· Note over 角色: 说明：添加注释

高级用法

sequenceDiagram
    Alice->>John: 你好John，最近怎么样？
    Note over Alice,John: 典型的寒暄
    John-->>Alice: 还不错，谢谢！
    
    loop 健康检查
        John->>John: 自我检查
    end
    
    alt 生病了
        John->>Alice: 我需要请假
    else 健康
        John->>Alice: 一切正常
    end

四、类图 (Class Diagram)

classDiagram
    class Animal {
        +String name
        +int age
        +eat()
        #sleep()
        -die()
    }
    
    class Dog {
        +bark()
    }
    
    class Cat {
        +meow()
    }
    
    Animal <|-- Dog
    Animal <|-- Cat
    Animal : +isAlive bool

三个符号的含义

在 Mermaid 类图中，+、-、# 是可见性符号，用于表示类中属性和方法的访问权限，这个概念来源于 UML（统一建模语言）。

符号	名称	访问权限	含义
+	public	公有	任何类都可以访问
-	private	私有	只有当前类内部可以访问
#	protected	受保护	当前类及其子类可以访问

代码示例

classDiagram
    class 动物 {
        +String 名称
        -int 年龄
        #String DNA序列
        +吃()
        -睡觉()
        #呼吸()
    }
    
    class 狗 {
        +汪汪叫()
        -追尾巴()
    }
    
    动物 <|-- 狗

实际代码中的对应关系, Java 示例

public class 动物 {
    public String 名称;        // + 对应 public
    private int 年龄;           // - 对应 private
    protected String DNA序列;   // # 对应 protected
    
    public void 吃() {}        // + 对应 public
    private void 睡觉() {}      // - 对应 private
    protected void 呼吸() {}    // # 对应 protected
}

其他可见性符号

在完整的 UML 规范中，还有：

~：包级可见性（Package，同一包内可访问）
/: 派生属性（Derived，从其他值计算得出）
$: 静态成员（Static，类级别）

在类图中的完整使用示例

classDiagram
    class User {
        +String username
        -String password
        #String email
        +login()
        -encryptPassword()
        #validateEmail()
        $int userCount
        +getUserCount()$
    }

这个类图表示：

username：公开可读
password：私有，外部不能直接访问
email：受保护，子类可访问
userCount：静态变量
getUserCount()：静态方法

关系符号：

<|–：继承
*–：组合
o–：聚合
–>：关联
…>：依赖
…|>：实现

五、状态图 (State Diagram)

stateDiagram-v2
    [*] --> 待机
    待机 --> 运行: 开机
    运行 --> 待机: 关机
    运行 --> 休眠: 超时
    休眠 --> 运行: 唤醒
    运行 --> 故障: 错误
    故障 --> 待机: 重置

六、甘特图 (Gantt Chart)

gantt
    title 项目进度计划
    dateFormat YYYY-MM-DD
    section 设计阶段
    需求分析    :a1, 2024-01-01, 7d
    原型设计    :a2, after a1, 5d
    section 开发阶段
    前端开发    :b1, after a2, 10d
    后端开发    :b2, after a2, 12d
    联调测试    :c1, after b2, 5d

七、饼图 (Pie Chart)

pie
    title 编程语言使用率
    "JavaScript" : 45
    "Python" : 30
    "Java" : 15
    "其他" : 10

八、实体关系图 (ER Diagram)

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER {
        string name
        string email
    }
    ORDER {
        int orderNumber
        date orderDate
    }

九、思维导图 (Mindmap)

mindmap
    root(项目计划)
        需求分析
            用户调研
            竞品分析
        设计
            UI设计
            架构设计
        开发
            前端
            后端
        测试
            单元测试
            集成测试

十、Git 图 (Git Graph)

gitGraph
    commit id: "初始提交"
    branch feature
    checkout feature
    commit id: "添加功能A"
    commit id: "添加功能B"
    checkout main
    merge feature
    commit id: "发布v1.0"

十一、高级技巧

1. 自定义样式

graph LR
    A[开始] --> B[处理]
    style A fill:#f9f,stroke:#333,stroke-width:4px
    style B fill:#bbf,stroke:#f66,stroke-dasharray: 5 5

2. 点击事件

graph LR
    A[点击跳转] --> B[目标页面]
    click A "https://mermaid.js.org" "打开文档"

3. 配置选项

mermaid.initialize({
    theme: 'default', // 'default', 'forest', 'dark', 'neutral'
    flowchart: {
        useMaxWidth: true,
        htmlLabels: true,
        curve: 'basis'
    },
    sequence: {
        showSequenceNumbers: true
    }
});