mermaid
把图表当代码写，让文档与开发同步
预览
详细介绍
图表即代码（Diagrams as Code）”——它不满足于传统的拖拽式绘图，而是让你用写Markdown的方式写流程图、时序图、类图、甘特图等专业图表，彻底解决文档与代码脱节（Doc-Rot）这一困扰开发者的经典难题。市面上大多数图表工具——Visio、Draw.io、Lucidchart等——都依赖拖拽操作和二进制文件存储，图表一旦生成就变成静态图片，当需求变更时要么重新画一遍，要么忍受文档过时；而Mermaid通过将图表定义以纯文本形式与代码共存于版本控制系统中，让图表像代码一样可追踪、可修改、可复用，从根本上改变了“文档滞后”这个长期痛点。
一、Mermaid是什么
Mermaid是一个基于JavaScript的开源图表库，通过解析类似Markdown的简洁文本语法，动态生成和修改各种专业图表。其技术架构分为三部分：语法解析器（将文本转换为抽象语法树）、布局引擎（计算节点位置与连线）、渲染层（支持SVG/PNG输出）。它原生集成于GitHub、GitLab、Notion、Obsidian、Typora、Jupyter、Docusaurus等众多平台和应用中，也可以在任何支持JavaScript的环境（VS Code、浏览器、Node.js）中以插件形式引入。
该项目在GitHub上已获得超过85.9k Star、9k Fork，于2019年获得JS Open Source Awards“最令人兴奋的技术使用”奖项。2026年以来项目持续快速迭代，v11.13.0版本新增了维恩图（Venn diagram，beta）和石川图（Ishikawa/fishbone diagram，beta）两种图表类型，并修复了标签解析兼容性问题，同时改进了流程图、ER图、甘特图、状态图和gitGraph等已有的核心图表类型。Mermaid采用MIT协议，完全开源免费，其官方提供在线编辑器（mermaid.live），用户也可以在本地通过Docker或npm部署私有化版本。
Mermaid的核心价值在于解决“文档-代码不匹配”这一技术文档领域的老大难问题。传统图表一旦生成便难以更新，而Mermaid将图表嵌入Markdown后，可以随代码一同提交至Git仓库，图表内容以纯文本存储，支持git diff追踪变更，彻底解决了二进制文件无法合并冲突的问题。
二、Mermaid能做什么
Mermaid的核心能力可以精炼地概括为：流程、时序、结构、进度、关系，围绕这五大维度提供了丰富且持续扩展的图表类型，具体包括：
流程图（Flowchart）——Mermaid最核心的功能之一。语法简洁明了，例如graph TD A[开始] --> B{判断}即可定义节点和箭头方向。支持形状变换（方框、圆角框、菱形、圆形等）和样式定制。相比传统绘图软件，用Mermaid画流程图的速度可提升80%以上，修改时只需调整文本描述即可。v11.13.0版本进一步新增了半箭头和中心边连接等功能，让流程图表达更加丰富。
时序图（Sequence Diagram）——适合描述对象或参与者之间的交互序列。用文本定义参与者（participant）、消息（->>）和箭头样式，即可呈现调用时序。新增alias支持让参与者命名更加灵活。
类图与ER图（Class Diagram & Entity Relationship Diagram）——类图适用于系统设计文档中的类结构建模；ER图用于数据库设计。类图中新增了命名空间内注释放置功能，ER图修复了边标签定位和数字“1”的基数识别问题。
甘特图（Gantt Chart）——项目管理场景的首选。用gantt关键字、日期格式和任务区间即可定义项目计划，支持任务依赖（after语法）和分区，实测复杂甘特图生成时间从传统方式的30分钟降至12分钟。
状态图（State Diagram）——展示系统状态转换，修复了冒号在过渡和状态描述文本中的使用限制。
Git图（GitGraph）——可视化Git分支与提交历史，对代码仓库的可视化分析和教学演示十分实用。
用户旅程图（User Journey Diagram）——描述用户在系统中的操作路径和行为体验，适用于产品设计文档。
象限图（Quadrant Chart）——四象限分析工具，常用于战略规划场景。
需求图（Requirement Diagram）——系统需求建模与追踪。
饼图（Pie Chart）——数据占比展示。
维恩图（Venn Diagram，beta）——v11.13.0新增，用set定义集合、union定义交集，支持大小比例控制和CSS样式定制，填补了Mermaid长期缺失的集合可视化能力。
石川图（Ishikawa Diagram，beta）——v11.13.0新增，也叫鱼骨图或因果图，用于质量管理中的根因分析。结构完全通过缩进定义，第一行是待分析的问题，缩进行代表各级原因，层次清晰直观。
除了图表类型，Mermaid还提供：
Live Editor在线编辑器——无需安装任何软件，直接在浏览器中访问mermaid.live即可使用。界面分为代码区和预览区，代码实时渲染，支持导出PNG、SVG和Markdown格式，历史记录自动保存最近30次编辑，还支持从GitHub Gist加载代码。
Mermaid Chart云端编辑器——由Mermaid团队打造的Web端图表编辑器，支持AI辅助绘图、团队协作、多用户编辑等高级功能。
CLI命令行工具（mermaid-cli）——可以在CI/CD流水线中批量将Mermaid代码转换为SVG或PNG，实现图表生成的完全自动化。目前CLI工具的v11.15.0版本持续更新依赖项。
安全机制——Mermaid提供安全级别选项（包括strict、loose、antiscript等），确保图表定义中的脚本或XSS攻击被适当隔离。文档中专门包含了安全与防篡改示意图的说明。
三、Mermaid适合谁用
Mermaid的功能特性使其适配各类有文档化需求、图表维护痛点和跨角色协作诉求的用户群体，核心覆盖以下几类：
软件工程师与架构师——日常编写技术文档、设计系统架构、做方案评审的开发者。Mermaid可以直接放在README、Wiki和代码注释中，修改需求时改几行文本图表就能同步更新，再也不用手动截图替换。实测数据显示，Mermaid已成为GitHub和GitLab的Markdown原生渲染格式，工程师用Mermaid的PR审查效率大幅提升。
技术文档工程师——负责撰写和维护API文档、用户手册、操作指南的文档团队。Mermaid让图表从“一次性绘制”变为“与文档代码协同演进”，彻底告别“文档滞后”的宿命。团队可以像管理代码一样管理和审阅文档中的图表变更。
项目经理与产品经理——项目管理中需要甘特图、需求图、用户旅程图来跟踪进度和规划产品。Mermaid可以嵌入项目管理文档，通过文本轻松调整任务周期和依赖关系，实现项目计划的可追溯版本管理。实际案例中，用Mermaid生成甘特图原本需要30分钟的工作缩减至12分钟。
DevOps与SRE工程师——CI/CD流水线自动化图表生成的首选工具。通过mermaid-cli，可以在部署流程中自动生成系统拓扑图、数据流向图或基础设施架构图的SVG，并嵌入到运维日报中。在Kubernetes文档和基础设施即代码（IaC）场景中，Mermaid也被官方文档广泛采用。
教育工作者与培训师——需要在课件、演示材料中绘制大量流程说明图的老师。Mermaid可以快速绘制算法流程图、系统交互时序图、网络拓扑图等，且所有图表以文本形式存在，便于修改和多次使用，非常适合在线课程和教材编写。
开源项目维护者——维护大型开源项目需要大量文档和贡献指南，Mermaid可以在GitHub中直接渲染流程图、时序图、架构图，帮助贡献者更好地理解项目结构。GitHub官方在2022年就已原生支持Mermaid，2026年GitHub上已有数百万个仓库通过Mermaid呈现项目架构。
数据工程师与数据分析师——需要生成ER图、数据流程图、管道依赖图的数据团队。Mermaid与Jupyter Notebook完全兼容，可在数据分析报告中嵌入实时生成的图表，让数据流可视化变得更加规范和可重复。
技术写作者与博主——撰写技术博客、教程的作者。Mermaid可以在Markdown中直接写图表代码，无需切换到外部绘图工具，博客更新时图表随之更新，不会出现“博客正文与配图不符”的尴尬。OneNote、语雀等笔记工具也原生支持Mermaid渲染。
从零开始的初学者——Mermaid语法与Markdown高度相似，学习成本趋近于零。一个从未画过流程图的人，花10分钟就能用Mermaid写出完整的登录流程并直接嵌入文档，改起来比改代码还快。
四、Mermaid的应用场景是什么
基于其核心功能与定位，Mermaid的应用场景主要围绕文档内嵌图表、架构可视化、项目管理、自动化生成和跨平台协作，覆盖从个人开发者到企业团队的多个场景，具体包括：
技术文档内嵌图表场景——传统技术文档中插入图表通常需要先打开第三方绘图工具→画图→导出图片→上传→嵌入链接→维护版本。Mermaid完全颠覆了这一流程：在Markdown的代码块中直接写graph TD; A-->B；，GitHub或GitLab会自动渲染为可视化图表。所有图表定义的文本与代码库共存，通过git diff可以精确追踪每一次图表变更，彻底避免二进制文件带来的合并冲突。Kubernetes官方文档中大量使用Mermaid来呈现架构和流程。
系统架构可视化场景——系统设计文档中的架构图需要随业务迭代频繁更新。Mermaid的C4架构图（Container/Context/Component/Code）让开发者用文本描述系统的分层结构，随代码一起进入版本库。当架构调整时，改动几行代码即可重新生成完整架构图，保持设计与实现同步演进。
项目进度跟踪场景——项目经理需要定期更新甘特图，但传统绘图工具维护成本高。Mermaid的甘特图模块支持任务依赖（after语法）、分区、里程碑标识，且可以嵌入到项目计划文档中，每次项目例会只需修改几行文本即可生成最新版进度图表。
数据库设计文档场景——数据工程师可以用ER图（实体关系图）来可视化数据库表结构及其关联。Mermaid的ER图支持实体定义、主键/外键标记和关系类型表示，修复后的版本解决了边标签定位和基数识别问题，非常适合在数据字典文档中动态维护数据模型。
CI/CD流水线自动化生成场景——在CI构建过程中通过mermaid-cli，可以自动生成代码分析报告中的架构图、数据流图，并嵌入到构建产物（如Javadoc、Sphinx文档等）中，实现“文档即产物、图表即代码”的自动化闭环。
AI驱动的图表生成场景——将DeepSeek等大模型与Mermaid结合，用户用自然语言描述需求（如“绘制用户注册流程，包含手机号验证和密码设置”），AI自动生成标准Mermaid代码，直接嵌入文档。实测复杂甘特图生成时间从30分钟降至12分钟，效率提升60%以上。LLM生态中Mermaid也是文本格式图表的最佳选择之一，因为语法简洁、与Markdown耦合度高，大模型学习和生成的成本远低于其他图表语言。
数据分析与可视化场景——在Jupyter Notebook中进行数据分析时，可以用Mermaid绘制数据流图、决策树和推理路径，既保持代码的完整性，又让分析过程的可视化与数据处理逻辑紧密耦合，便于同行评审和结果重现。Datadog Notebooks也原生支持Mermaid渲染。
教育与培训场景——在线课程平台、技术培训材料可以利用Mermaid快速生成算法流程图（排序算法、搜索算法等）、系统交互时序图和网络拓扑图，所有图表以纯文本形式存储，支持版本更新和协同编辑。虚拟课堂中使用Live Editor实时演示图表编辑过程，比PPT配图更灵活。
跨平台知识库场景——许多团队使用Notion、Obsidian等作为内部知识库，这些平台都原生支持Mermaid。团队可以在Notion中直接创建流程图、甘特图、类图，与文字说明并列呈现，且图表以文本格式存储，支持多人协作和版本历史。Obsidian的双链笔记结合Mermaid，让知识图谱自动可视化知识库结构。
五、Mermaid为什么值得关注
Mermaid之所以值得关注，核心在于它重新定义了技术文档中图表的生产和维护方式，将图表从“静态插图”提升为“与代码同等的文档资产”，同时具备广泛的生态渗透力和持续的社区生命力，具体体现在以下几点：
从“拖拽绘图”到“代码式绘图”的范式转移——传统图表工具本质上是图形编辑器，图表是独立的二进制文件或图片。Mermaid则不然：图表定义是Markdown文档的一部分，是纯文本，是可读的，可直接纳入版本控制。如果你能写Markdown，你就能用Mermaid画图。当需求变更时，修改几行文本，图表自动更新，而不是重新开一次Visio、重新截图、重新上传。
解决了“Doc-Rot”这一长期痛点——“Doc-Rot”（文档滞后）是软件开发中最常见的问题之一：开发者忙于写代码，文档和图表永远停留在第一版。Mermaid的设计初衷正是解决这一问题。让图表与代码生活在一起、通过版本控制追踪每一次变更、修改成本几乎为零——当更新图表比忽略图表还容易时，文档滞后的习惯自然被打破。
GitHub原生支持带来的生态爆发——2022年GitHub宣布原生支持Mermaid渲染以来，Mermaid的采用率呈指数级增长。目前GitHub、GitLab、Notion、Obsidian、Typora、Jupyter、Docusaurus等数十个主流平台均原生支持或提供集成插件。这意味着Mermaid用户零配置即可在这些平台上获得即时的图表渲染体验，生态壁垒已经形成。
全面的图表类型覆盖和持续演进——Mermaid早已不只是“画流程图”的工具。截至2026年，Mermaid支持超过16种图表类型，2026年4月的v11.13.0版本新增维恩图和石川图两种beta类型，同时在流程图、ER图、甘特图、状态图等方面都进行了深度优化和Bug修复。这种持续迭代的节奏和社区驱动的发展模式，让Mermaid在功能和稳定性上稳步超越同类工具。
跨平台兼容与零配置体验——浏览器端通过CDN引入即可使用；VS Code插件支持Markdown预览实时渲染；GitHub/GitLab在查看.md文件时自动渲染代码块；Docusaurus、Hexo、MkDocs通过插件支持嵌入。一次学习，处处可用，无需在不同平台上重复学习不同的图表工具。
与AI生态的天然契合——Mermaid以文本格式存储图表定义，与自然语言有着天然的亲和力。随着大语言模型的崛起，“用自然语言描述需求→大模型输出Mermaid代码”的工作流变得非常自然和高效。Mermaid已成为AI生成图表的首选输出格式之一，LLM的爆发进一步放大了Mermaid的覆盖面和用户基数。
活跃的开源社区与行业认可——Mermaid获得2019年JS Open Source Awards“最令人兴奋的技术使用”奖项，GitHub Star突破85.9k，Fork超过9k。无论是核心技术贡献（如v11.13.0的维恩图和石川图由社区成员@exoego在短期内完成全部实现）还是周边生态工具（如mermaid-cli、beautiful-mermaid、Pretty-mermaid-skills等），Mermaid的开源生态都显示出极强的生命力和扩展性。
与同类工具（PlantUML、Graphviz）的差异化定位——Mermaid在Markdown生态和GitHub原生渲染上具有绝对优势，对简单流程图、时序图、用户旅程图等“文档内嵌场景”最为友好。PlantUML则在UML专业类图、组件图、部署图上有更深厚的积累，但需要Java+Graphviz运行时环境。Graphviz的DOT语言在纯图论布局上最强大，但缺乏Markdown的“一次嵌入随处渲染”体验。这些工具各有侧重，但Mermaid凭借“纯JavaScript、无额外依赖、Markdown原生”这三张王牌，成为技术文档写作中门槛最低、最普及的选择。
商业支持与社区力量的良性互动
