如何 3 分钟上手 Mermaid 图表：一张流程图、3 种核心语法与完整项目集成指南
【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid
文档写完三个月没人再看，架构图改了五版却找不到最初为什么这么画的——这是大多数团队都踩过的坑。Mermaid 是 JavaScript 侧的一个图表库，用类 Markdown 的文本描述生成流程图、时序图这类图，随代码一起进版本库。这份 Mermaid 教程按上手顺序走：先在 Live Editor 里出图，再补核心语法，最后接进项目。
🚀 从 Live Editor 开始，3 分钟出第一张流程图
推荐入口是官方在线编辑器 Live Editor（mermaid.live）：浏览器打开就能画，不用装任何东西，也没有本地环境要配。
在左侧输入下面 5 行，右侧立即出图：
flowchart LR A[提交代码] --> B[跑 CI] B -->|通过| C[合并主干] B -->|失败| A几个马上能用上的点：
- 改一个字，预览立刻刷新，语法错了会有报错提示，适合边试边学；
- 代码会自动编码进 URL 地址栏，刷新页面内容不丢，换台电脑打开还能接着画；
- 画完点复制，把代码带进项目——后面所有集成用的都是这段文本，不依赖编辑器本身。
📝 核心语法：流程图、时序图、类图的最小写法
三种图覆盖日常大部分需求，各记住一个模板就行。
流程图：节点形状 + 箭头 + 边标签
- 形状：
[ ]矩形、( )圆角、{ }菱形判断、(( ))圆形、[( )]圆柱代表数据库； - 连线：
-->有向，<-->双向；竖线|文字|给边打标签； - 同一行链式写多个节点，能少写一半代码。
flowchart TD A[收到请求] --> B{已登录?} B -->|是| C[返回数据] B -->|否| D[跳转登录页]时序图：参与者 + 消息箭头
participant声明参与者；->>实线请求，-->>虚线响应；左右两个符号之间写self: 内容表示自调用。
sequenceDiagram 浏览器->>网关: 登录请求 网关->>认证服务: 校验凭证 认证服务-->>网关: 签发 JWT 网关-->>浏览器: 200 + token类图：属性方法 + 关系箭头
大括号内每行一个成员，-私有、+公开；<|--继承、--*组合、..>依赖。
classDiagram class 用户 { -String 用户名 +登录() } class 管理员 用户 <|-- 管理员其余类型不再逐个展开，需要时查这张速查表：
| 类型 | 一句话用途 | 最小语法 |
|---|---|---|
| stateDiagram-v2 | 状态机、工作流迁移 | [*] --> 就绪 |
| gantt | 项目排期、任务时间线 | section 设计+ 一行任务 |
| pie | 占比分布 | pie title 分布 "A" : 50 |
| mindmap | 知识结构、头脑风暴 | root((主题))+ 缩进分支 |
| erDiagram | 数据库实体与关系 | A \|\|--o\| B : 拥有 |
| timeline | 时间轴事件 | timeline+ 年份分行 |
| quadrantChart | 优先级四象限 | x-axis 快-->慢+ 点 |
| userJourney | 用户旅程体验评分 | section 步骤+metrics |
集成到项目：CDN 与 NPM 两条路
把图接进自己产品里，两条路：CDN 引入适合静态页和快速验证；npm 装包适合工程化项目，能跟着构建流程走。两种方式拿到的 API 一致，都从initialize开始。
<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11.9.0/dist/mermaid.esm.min.mjs'; mermaid.initialize({ theme: 'default', securityLevel: 'strict' }); </script>npm install mermaidinitialize只需要盯住四个关键项：theme（内置 default / forest / dark / neutral 四套）、securityLevel（strict 默认最稳，loose 才允许节点内交互）、startOnLoad（false 时手动mermaid.render渲染）、fontFamily。
三个最常见的坑：
- ES module 报错：npm 装完 import 失败，多半是 package.json 没声明
"type": "module"，改成 .mjs 后缀或补上声明即可；CDN 侧注意要用type="module"的 ESM 文件； - 版本漂移：CDN 导入或装包时锁定具体版本号，别用 latest，大版本升级可能改变默认渲染行为；
- 渲染时机：目标容器必须已在 DOM 里再调用
render；把图定义放在 JS 字符串里传参，比写在 DOM 里等解析更省心。
进阶：主题、分享与文档站 / CI 渲染
主题与配色：theme一键换风格；想贴近站点视觉，就在themeVariables里微调primaryColor、lineColor这类变量，全局统一生效。
URL 分享协作：Live Editor 会把当前图表编码进 URL，把地址发给同事，对方打开看到的就是同一张图，不用来回贴代码。
文档站与 CI 流水线：GitHub、GitLab 等平台原生识别```mermaid代码块；文档站里写图就是敲代码块，改文字即改图。配合 mermaid-cli 工具还能把.mmd文件批量转成 SVG 提交进仓库——提交文档的同一张 PR 里，CI 顺手把图更新掉，不存在"文档是新的、图是旧的"。
学习资源：语法细节以官方文档（mermaid.js.org 的 Syntax 分区）为准；本仓库的 demos/ 目录有每种图的独立示例页，docs/syntax下则是按图分类的语法文档，可直接对照查。
适合：代码仓库文档、技术博客、CI 自动化生成的图表；不适合：像素级精确排版、复杂插画类需求（交给专业绘图工具）。官方文档 mermaid.js.org，示例集 mermaid.live。
【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
