mermaid

从「画图焦虑」说起：Mermaid 如何让技术文档重获呼吸

写过技术文档的人大概都有过这样的经历：需要画一个流程图或时序图，打开 Visio 或 Figma，拖拽半天，终于对齐了形状，调好了线条粗细——然后需求变更，整个图要重做。这种"图形工具反被图形工具役"的情况，是技术写作中最普遍的时间陷阱。

Mermaid 正是来解决这个问题的。它用一个极简的类 Markdown 语法，让用户用纯文本就能描述图表：流程图、时序图、类图、甘特图……写完即图，Git 管理、版本对比统统支持，改需求改文本就行，再也不用在设计软件里来回折腾。

开源明星的进化史

Mermaid 诞生于 2012014 年，最初由 Knut Sveidqvist 发起，最初定位是"用文本描述图表的 JavaScript 库"。项目最初用 Node.js 构建，后来逐步演化为支持浏览端渲染的纯前端工具。随着 GitHub 全面支持在 Markdown 中嵌入 Mermaid 代码，项目迎来了爆发式增长——如今 GitHub README、GitLab 文档、Notion、Obsidian、飞书等主流平台均已内置 Mermaid 渲染。

2019 年，Mermaid 获得了由 npm 颁发的 JavaScript Open Source Award"最激动人心的技术应用奖"，成为图表类工具的事实标准。截至 2026 年初，GitHub 星标数超过 88,000，是同类开源图表工具中 Star 最多的项目。

2024 年，项目正式迁移至 mermaid.ai 域名，并推出官方平台 Mermaid Chart，完成了从开源库到商业生态的延伸。

类比解释：给你的文字装上「图形引擎」

如果说 Markdown 是给普通文本装上了格式引擎，那么 Mermaid 就是给技术文本装上了图形引擎——它把「描述性语言」翻译成「可视化图形」，你只需要写"说什么"，它来处理"长什么样"。

举个例子，下面这段文本：

graph TD
  A[开始] --> B{判断条件}
  B -->|是| C[执行操作]
  B -->|否| D[返回结果]

自动渲染为一个带菱形判断节点的流程图。开发者可以直接把这段代码嵌入代码仓库的 README 中，Git 记录了历史，reviewer 直接看到图形，协作效率大幅提升。

支持的图表类型

Mermaid 目前支持超过 20 种图表类型，覆盖技术文档的方方面面：

流程图类包括标准流程图（Flowchart）和思维导图（Mindmap），用于展示系统架构和思路结构；时序图类有时序图（Sequence Diagram），用于描述系统组件间的消息交互逻辑，是 API 设计评审的必备工具；结构图类包括类图（Class Diagram）和状态图（State Diagram），支持面向对象分析和状态机建模；数据可视化类支持饼图（Pie）、甘特图（Gantt）、Sankey 图等，其中甘特图在项目管理文档中尤为实用；特殊图表类包括 Git 提交图（GitGraph）、用户旅程图（User Journey）、架构图（Architecture）、雷达图（Radar）等，满足各垂直场景需求；最新版本还引入了 C4 模型图、Packet 图、Kanban 图等新兴类型，持续扩展边界。

技术架构：monorepo 下的精密工程

Mermaid 采用 pnpm workspace 构建 monorepo 架构，主包位于 packages/mermaid，包含核心渲染引擎、解析器、布局算法等核心模块。此外还有 mermaid-local-editor（本地版 Live Editor）、mermaid-layout-elk（ELK 布局引擎）、mermaid-layout-tidy-tree（树状布局引擎）等扩展包。项目使用 Vitest + Cypress 进行单元测试和端到端测试，CI 流水线完整，覆盖率较高。

核心渲染链路为：文本语法 → 解析器（Parser）→ 抽象语法树（AST） → 布局引擎 → SVG/HTML 渲染。所有渲染在浏览器端完成，无需服务端，支持 iframe 嵌入，天然适合文档工具集成。

技术栈方面，项目主语言为 TypeScript（超过 88k Star 的 TypeScript 项目），辅以 JavaScript。使用 D3.js 进行图形布局，借助 jsdom/chrome-puppeteer 实现 SSR 场景下的服务器端渲染。

部署体验：一键启动的 Live Editor

Mermaid 提供了功能完整的在线编辑器（Live Editor，https://mermaid.live/），用户无需安装即可在浏览器中实时预览图表效果。对于本地开发，项目提供了 docker-compose.yml，一行命令即可启动完整的 Live Editor 开发环境：

git clone https://github.com/mermaid-js/mermaid.git
cd mermaid
docker compose up

这使得 Mermaid 既可以作为零依赖的 npm 包集成到现有前端项目中，也可以作为独立服务部署，提供团队共享的图表编辑平台。

局限与争议

Mermaid 并非没有局限。由于采用文本语法，某些高度定制化的图形需求（如精确的位置控制、复杂的渐变样式）难以实现，复杂图表的自动布局有时不如手绘精确。此外，随着商业化推进（Mermaid Chart 平台），社区对开源可持续性的关注度有所提升，部分用户担忧核心功能的商业锁定。

行业意义

Mermaid 的意义远超一个图表工具本身。它代表了一种"代码即文档"（Documentation as Code）的理念延伸——图表同样可以被版本控制、被代码审查、被自动化测试。这种理念正在深刻影响技术写作领域，推动文档从"静态产物"向"动态可执行资产"转变。在 AI 代码助手时代，Mermaid 的文本语法特性使其天然适配 LLM 生成，是 AI 辅助技术文档生成的理想载体。