以下是 Mermaid.js 的 安装方法、使用步骤 和 常见语法 的完整指南，涵盖核心功能和快速上手示例：

一、安装方法

1. 浏览器直接使用（CDN）

<!-- 在 HTML 文件中添加以下代码 -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"></script>
<script>
  mermaid.initialize({ startOnLoad: true }); // 初始化并自动渲染所有图表
</script>

2. 通过 npm/yarn 安装

npm install mermaid
# 或
yarn add mermaid

3. 框架集成示例

  • React：

import React, { useEffect } from 'react';
import mermaid from 'mermaid';

const MermaidChart = ({ code }) => {
  useEffect(() => {
    mermaid.initialize({ theme: 'dark' });
    mermaid.init(undefined, document.querySelectorAll('.mermaid'));
  }, []);
  return <div className="mermaid">{code}</div>;
};

  • Vue：

<template>
  <div class="mermaid">{{ code }}</div>
</template>
<script>
import mermaid from 'mermaid';
export default {
  mounted() {
    mermaid.initialize({ startOnLoad: true });
    mermaid.init();
  }
};
</script>

二、使用步骤

1. 基础使用（HTML 中渲染）

<div class="mermaid">
  graph LR
    A[开始] --> B[结束]
</div>

2. 动态渲染（通过 JavaScript API）

<div id="diagram"></div>
<script>
  const code = `
    graph TD
      A --> B
      B --> C
  `;
  mermaid.mermaidAPI.render('diagram', code, (svgCode) => {
    document.getElementById('diagram').innerHTML = svgCode;
  });
</script>

3. 配置全局参数

mermaid.initialize({
  theme: 'forest',       // 主题：default / dark / forest / neutral
  flowchart: { curve: 'basis' }, // 流程图线条样式
  securityLevel: 'loose' // 允许渲染外部内容（如禁用安全限制）
});

三、常见语法与示例

1. 流程图（Flowchart）

graph LR A[开始] --> B{条件} B -->|是| C[操作] B -->|否| D[结束] C --> D

  • 方向：LR（左右）、TD（上下）

  • 节点类型：

    • 矩形：A[文本]

    • 菱形：B{文本}

    • 圆形：C(文本)

  • 连接线：-->（实线）、-.->（虚线）、-- 文字 -->（带文字）

2. 序列图（Sequence Diagram）

sequenceDiagram Alice->>Bob: 消息1 Bob-->>Alice: 响应1 Alice->>Bob: 消息2

  • 参与者：自动生成或手动定义 participant Alice

  • 消息类型：

    • ->>：实线箭头

    • -->>：虚线箭头

    • ->>+Note right of Bob: 注释：添加注释

3. 甘特图（Gantt Chart）

gantt title 项目计划 dateFormat YYYY-MM-DD section 阶段A 任务1 :a1, 2023-01-01, 30d 任务2 :after a1, 20d

  • 时间格式：dateFormat 定义日期

  • 依赖关系：after 关键字指定任务顺序

4. 类图（Class Diagram）

classDiagram class Animal { +String name +void eat() } Animal <|-- Dog : 继承

  • 类成员：+ 表示公有，- 表示私有

  • 关系：

    • 继承：<|--

    • 组合：*--

    • 聚合：o--

5. 饼图（Pie Chart）

pie title 数据占比 "类别A" : 45 "类别B" : 55


四、调试与工具

1. 常见问题

  • 图表不渲染：检查语法缩进和符号（如 --> 是否正确）。

  • 安全限制：配置 securityLevel: 'loose' 避免内容被拦截。

2. 在线工具

3. 结合 Markdown

  • GitHub/GitLab：原生支持 Mermaid（直接插入代码块）。

  • VS Code：安装插件 Markdown Preview Mermaid Support。

五、总结

  • 安装：CDN、npm 或框架集成。

  • 使用：编写文本语法，调用 mermaid.initialize() 渲染。

  • 语法：流程图、序列图、甘特图等核心图表语法。

  • 调试：利用在线工具和浏览器控制台。

官方文档：Mermaid.js Docs