企业官网建设流程全解析

Mermaid：用 Markdown 风格文本画图，5 分钟跑通 20 种图表

【免费下载链接】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 的文本描述流程图、时序图、类图、甘特图等 20 余种图表。它把"画图"变成"写文档"，让图表随代码一起版本控制，从根上缓解文档腐化问题。本文覆盖安装、核心能力、真实场景与常见坑，读完即可动手。

为什么文本能替代画图工具

画图表和写文档都费时，且都容易过时；可是不画图、不写文档，团队学习和协作效率又直接受损。这是一个两头堵的困境。

Mermaid 的解法是把图表定义成文本：图表代码可以提交进 Git，随功能一起修改、一起评审、一起回滚。和传统导出图片相比，它带来三个直接好处：

• 可 diff：改了一个节点、加了一条连线，代码评审时一眼可见；
• 可回滚：图坏了？git revert就行，不用翻聊天记录找旧版本；
• 可自动化：构建脚本能批量渲染图表，文档和实现永远不会"对不上"。

这个项目由 Knut Sveidqvist 创建，MIT 许可，2019 年拿过 JS 开源奖"最具技术激情的应用"。目前版本已迭代到 11.x，仍在高频发版。

3 分钟上手

最短路径：装包、调 API、渲染。

npm install mermaid # 需要 Node.js 20+

import mermaid from 'mermaid'; const { svg } = await mermaid.render('diagram', 'graph TD\n A[开始] --> B[结束]');

render返回渲染好的 SVG 字符串，插进任意 DOM 节点即可。静态页面也可以更省事：把图表写进<pre class="mermaid">，再用 CDN 引入库并调用mermaid.initialize({ startOnLoad: true })。不想碰代码的话，官方在线编辑器 mermaid.live 支持实时预览，并可直接导出 PNG、SVG 或 Markdown。

核心配置项不多，最常用的四个如下：

核心能力：20+ 种图表，一套语法风格

所有图表都遵循同一节奏：首行声明图表类型，后面是内容定义，%%开头是注释。挑四个最常用的看：

其余图表按用途归四类：

完整列表还有思维导图、时间线、C4 架构图、用户旅程、象限图、桑基图、雷达图等，每种都有独立语法文档。

两个能显著提升表达力的机制值得单独提。一是frontmatter 配置：在图表代码前加 YAML 头，可以为单张图覆盖主题、布局等全局设置，不动 JS 代码。二是多布局算法：内置 dagre、elk、tidy-tree、cose-bilkent 四种自动布局，节点一多就换算法：

--- config: layout: elk --- graph TD A --> B B --> C

真实场景

场景一：技术文档与代码同步。写文档的人最烦"图比代码旧三个月"。常见痛点是图片导出后散落在各处，没人敢动。Mermaid 让图表以代码块形式存在文档里，改动即渲染、提交即存档，评审时 diff 清清楚楚。

场景二：渲染用户提交的图表。公共站点直接展示外部输入的图表有风险——图表源码里含大量 HTML 字符，常规清洗反而会破坏图。常见痛点是不知道防护该做到什么程度。Mermaid 从 8.2 起提供 securityLevel：默认 strict 会把 HTML 标签编码并禁用点击交互；对纯外部用户内容可选 sandbox，在隔离 iframe 里渲染、彻底禁止脚本执行。注意取舍：防得更严，交互功能就会被一并挡掉。

场景三：大型系统架构图。节点一多，拖拽工具就开始乱线、手抖、没法改。Mermaid 用文本声明式地描述结构，增删节点只改一行；复杂流程换 elk 布局，效果立见分晓。

上手常见坑

• 流程图里出现end这个词？会中断解析，给它加引号即可。
• frontmatter 不生效？第一个---必须是文件第一行，且是那一行唯一的内容。
• 渲染报错了 vs 参数被忽略了？未知单词会直接打断图表，参数拼错则静默失效。报错查语法，没效果查参数名。
• 页面多张图互相干扰？每张图放进各自独立的<pre class="mermaid">标签里。

生态与社区

• 官方在线编辑器 mermaid.live：实时预览、历史草稿（存在浏览器本地）、一键导出 PNG / SVG / Markdown；
• 配套命令行工具 mermaid-cli，可在 CI 里把图表批量转成图片或 PDF；
• GitHub、GitLab 等支持 Markdown 的平台可直接渲染mermaid代码块，无需额外插件；
• 仓库采用 pnpm workspace 的 monorepo 结构，核心库在 packages/mermaid，ELK 布局等作为独立包拆分，贡献指南见 docs/community/contributing.md；
• 近期 11.17.0 新增了可折叠流程图子图、person 节点形状、ER 图子图支持，发版节奏稳定。

写在最后

Mermaid 把"画图"降维成"写文本"，图表从此能进版本库、能过评审、能自动化。如果你是被文档腐化困扰的开发者，或需要维护架构图、时序图的团队作者，它值得放进你的工具箱。下一步，去 docs/intro/syntax-reference.md 查语法参考，挑一种图表开始写。

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