Mermaid：文本驱动图表，把 ER 图、流程图写进文档并纳入版本控制

Mermaid：文本驱动图表，把 ER 图、流程图写进文档并纳入版本控制

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid

数据库表结构刚改完，文档里的 ER 图还是三个月前的样子——这是多数技术团队都遇到过的场景。传统做法是重新打开画图工具、找到当时的文件、对照表结构一格一格地改。Mermaid 走的是另一条路：它是一个 JavaScript 库，把类 Markdown 的文本语法直接渲染成 SVG 图表。

Mermaid 编辑器里，左侧是 ER 图语法文本，右侧是实时渲染结果

把图表写成文本，先解决三件具体的事：

图和内容不再失步。图表从 GUI 工具导出成 PNG 或 SVG 之后，就成了与文档脱节的静态文件；表结构变了、流程调整了，图还停在导出那天，也很少有人再回去更新。Mermaid 把图描述成文本，文本与它描述的内容放在同一个文件里，改完提交，图和文档天然同步。

协作不依赖文件交换。传统工具里改图意味着导出二进制文件、走文件交换流程、再重新打开软件；Mermaid 的图是纯文本，可以直接在 Pull Request 里做 diff，评审者能看到每个节点标签的改动，合并后图自动跟着代码版本走。

每一次变更都有记录。图表文本进入 Git 后，git log能回答"这张流程图是哪一次变更改的、谁改的、为什么改"，GUI 导出物做不到这一点。

按场景选图型：流程、交互、进度

Mermaid 支持 20 多种图型，按使用场景挑：

梳理业务逻辑：flowchart 覆盖带判断分支和回环的流程——订单先校验库存，通过则扣减，失败转人工，回环用一条虚线表示就够了；状态图适合订单、工单这类有明确生命周期的对象。

描述系统交互与数据模型：时序图按时间轴展示消息传递与返回值，微服务调用链、API 请求流程画起来最直观，下面这张图由十几行文本生成：

ER 图与类图描述静态结构，数据库表关系、领域模型各有一席之地。

追踪进度与演化：甘特图支持排除指定日期、after依赖和里程碑标记，迭代排期调整后改文本即可，不必重画时间轴：

gitgraph 则用来复盘提交历史，评审重构前后的分支走向时派得上用场。

引入 npm 包、渲染第一张图、用 mmdc 导出

引入：

pnpm add mermaid

渲染：初始化一次，把图语法文本交给render：

import mermaid from 'mermaid'; mermaid.initialize({ startOnLoad: true });

第一张图，文本即图：

flowchart TD A[开始] --> B{库存充足?} B -->|是| C[扣减库存] B -->|否| D[转人工] C --> E[生成订单] D --> E

以上语法与更多图型的完整说明见 docs/syntax/ 目录；主题、安全级别、字体等配置项在 docs/config/ 里有逐项解释，其中securityLevel设为strict会启用沙箱（隔离执行环境，阻止图表内代码访问宿主页面），页面里会混入用户可控内容的团队建议默认开启。

大图的渲染开销主要来自 HTML 标签节点：关闭htmlLabels可以明显减少 DOM 数量；单张图超过两屏时，更稳的做法是按模块拆成子图分别渲染。

导出：命令行工具mmdc把.mmd文件批量转成 SVG 或 PNG，放进 CI 就能在构建产物里附带最新图——README 改了一行文本，架构图随这次提交自动重出。具体参数见 docs/config/mermaidCLI.md。

平台原生支持与社区生态

• 平台侧：GitHub、GitLab、VS Code、Notion、Obsidian 都能直接渲染 Mermaid 代码块，文本贴进去即是图，无需额外插件
• 语言集成：Python、Java 等语言的社区库，可在脚本里生成图表文件
• 构建工具：Webpack、Vite 均有配套插件，让文档流水线直接消费渲染产物
• 自定义图型：仓库内的packages/mermaid-example-diagram目录是官方示例扩展，照着补上解析逻辑与渲染函数即可定义领域图型

更多集成方案与教程集中在 docs/ecosystem/ 目录。

三个高频问题

如何导出图片？用mmdc命令行，或在线编辑器页面上的"Download SVG / PNG"按钮，两者产物一致。

图表内容来自用户输入时怎么防注入？initialize传securityLevel: 'strict'，沙箱会拦截图表内代码对宿主页面的访问。

渲染太慢怎么办？关闭htmlLabels、按模块拆分大图，二者通常比调参更有效。

图跟着文字走，文字在文档和版本库里，图就不会掉队——这是 Mermaid 把"画图"变成"写文本"之后换来的全部收益。

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid