上周三晚上十一点，我在微信群里把新项目的模块依赖图发出去，同事回了一句：“这图你是用draw.io画的吧？改了三次，git记录里全是XML diff。”那一刻我意识到，对写代码的人来说，流程图早就不是“画”出来的，而是“写”出来的。而把写图这件事做到极致的，就是VSCode里那套Mermaid插件组合。
这篇东西我不打算讲太多虚的，直接说清楚三件事：为什么Mermaid配VSCode是我用过最顺手的方案、怎么在5分钟内搭出一个能实时预览的流程图环境、以及我踩了一整年后沉淀下来的报错排查经验。适合所有用VSCode写文档、写设计稿、写汇报材料的开发者，尤其是那种“流程图改起来比写代码还痛苦”的群体。
1. 为什么偏偏是VSCode + Mermaid 这套组合
1.1 从一次技术方案评审说起
大概两年前，我参与一个中台项目的方案评审。当时架构师用Visio画了一张复杂的时序图，评审会上改需求，他当场改图改了20分钟，全场等着他拖框拉线。散会之后，他把源文件发到群里，我点开一看，里面全是图层和坐标，想帮他加一个分支，完全无从下手。
那次之后，我就开始尝试用文本方式画图。试过PlantUML、Graphviz，也用过在线的mermaid live editor，但始终觉得别扭。PlantUML语法不算难，可Java环境的安装就让不少同事劝退；Graphviz能画得很精细，但写出来的dot代码可读性太差。直到有一天我在某个开源项目的README里看到一段 ```mermaid 代码块，复制到本地VSCode里一看，干干净净的图直接渲染出来了，再也没有“拖框拉线”这件事。
Mermaid本身是JavaScript写的渲染库，把图表的描述写成文本，解析后输出SVG。它最大的优势不是功能多么强大，而是“图即代码”：可以进Git、可以diff、可以在任何支持它的编辑器里即时渲染。这正好补上了VSCode作为文档编辑器的最后一块短板——你写markdown、写代码、写配置，现在连流程图都能在同一套工作流里完成了。
1.2 Mermaid到底解决了什么问题
很多没真正用过Mermaid的人，会觉得它就是个“简易流程图工具”，替代品是draw.io或者ProcessOn。但实际用下来，它解决的核心痛点是“流程图的版本管理”和“流程图的协作成本”。
拿我们团队举例，接口文档里的调用流程图、支付模块的状态机图、数据库迁移的时序说明，全部用Mermaid写在markdown文件里。代码评审的时候，图跟代码放在同一个MR（Merge Request）里，评审人不用跳转到外部系统看图，修改意见直接指向文档的某一行，提交记录里能看到这张图是在哪个版本加了哪个分支。这些东西，传统拖拽式工具无论如何都给不了。
另外，Mermaid的图不是静态图片，它支持用户交互。节点上可以挂点击跳转链接，可以配置tooltip，某些场景下还能嵌进HTML和Vue组件里。我在做内部系统的时候，就把接口调用的时序图直接渲染到前端的帮助文档页面里，运维同事点开某条时序图就能看到每个步骤对应的日志关键字，排查问题不再需要翻wiki。
1.3 哪些人最适合用这套方案
如果你符合以下任何一条，我都建议你把Mermaid用起来：
- 写技术方案、接口文档、系统设计文档，需要经常插入流程图的研发、测试、运维工程师
- 做产品原型说明、需求文档，需要表达用户路径和状态流转的产品经理、交互设计师
- 写课程讲义、实验指导书，需要大量示意图的教师、培训讲师
- 写公众号、知乎、博客，经常用流程图辅助讲解的技术写作者
这套方案的下限很低，装个插件就能用；上限也不算低，配合自定义主题、子图、图表混排，能做出接近专业绘图软件的效果。最关键的是，整个环境开箱即用，基本不依赖外网服务，离线环境也稳定。
2. 5分钟搭好实时预览环境：选插件的门道都在这里
2.1 VSCode安装与基础准备
大多数写代码的人机器上已经有VSCode了，但为了不跳过任何步骤，我还是提一嘴。官方安装包从官网下载，安装时建议勾选“添加到PATH”和“通过Code打开操作”这两个选项。虽然Mermaid预览不依赖PATH，但装了之后方便你在终端里直接用code 某个文件打开项目，属于高频小便利。
VSCode装好后，建议先把中文语言包装上。虽然Mermaid语法和插件界面都是英文，但VSCode的中文设置会让你在建工作区、修配置文件的时候更不容易出错。打开扩展面板（Ctrl+Shift+X），搜索“Chinese Language Pack”，安装后按右下角提示重启即可。
2.2 插件选型：我踩过的对比清单
VSCode里跟Mermaid相关的插件少说也有七八个，我几乎都试过，最后留下了两个主力，各有分工。
| 插件名 | 核心能力 | 适用场景 | 备注 |
|---|---|---|---|
| Markdown Preview Enhanced | Markdown增强预览，内置Mermaid、PlantUML、Katex、图表渲染 | 日常写文档、技术方案、带公式和流程图的复合文档 | 功能多，配置项丰富，导出能力强 |
| Markdown Preview Mermaid Support | 轻量级Mermaid渲染支持，专注把代码块里的mermaid变成图 | 只写纯markdown，不希望引入过多全家桶 | 简单直接，启动快，跟VSCode原生命pdf风格接近 |
刚开始我用的是Markdown Preview Mermaid Support，因为它够轻，打开.md文件就能看到 ```mermaid 渲染出来的图，左下角还有个“预览侧边”的按钮，一键打开分屏。后来频繁遇到一个场景——需要在文档里同时放流程图和表格、数学公式，这个插件就有点不够用了，我换到了Markdown Preview Enhanced，也就是社区里常说的MPE。
MPE最吸引我的点在于绝不只是支持Mermaid，它还支持PlantUML、Graphviz、ECharts，以及基于puppeteer的导出PDF、PNG、HTML。举个例子，我要把一篇带流程图的技术方案导成PDF发给客户，原生的VSCode预览做不到，MPE右键预览窗口选择“Export to PDF”，出来的PDF里流程图是矢量图，放大不糊，这一下就解决了我之前的交付痛点。
2.3 安装与核心配置项
以Win11为例，装完上述任意一个插件后，打开任意一个markdown文件（后缀必须是.md），输入以下内容：
```mermaid graph TD A[开始] --> B{是否注册} B -- 是 --> C[进入首页] B -- 否 --> D[跳转注册页] ```然后按Ctrl+Shift+V打开预览。MPE默认会启用Mermaid渲染，如果你用的是Markdown Preview Mermaid Support，同样按这个快捷键就能看到图了。
这里有一个小坑，如果你装了MPE却发现mermaid代码块没有被渲染成图，而是变成了一段代码文本，大概率是MPE的脚本执行被关闭了。打开设置（Ctrl+,），搜索enableScriptExecution，把Markdown-preview-enhanced: Enable Script Execution选项勾上，再回到预览窗口点刷新，图就出来了。
用MPE还有个我认为值得调的设置：在设置里搜索mermaid theme，通常有default、dark、forest、neutral这几个主题。我自己常用的是dark，配合VSCode的深色主题，整体观感一致。设置项是保存在工作区还是用户级，看你个人习惯，我建议放在用户级，这样换项目不用重新配。
3. 从零到能用的实操路径：语法、渲染与细节调优
3.1 最小可用示例： graph TD 与 graph LR 的差异
Mermaid的流程图语法分成两类开头，一类是graph，一类是flowchart。graph是早期语法，flowchart是更推荐的新语法，功能更丰富，但绝大多数场景下graph已经够用。graph TD表示从上到下布局（Top Down），graph LR表示从左到右布局（Left Right）。
我自己的经验是：描述业务流程、审批流、状态流转，用TD更符合阅读习惯；描述模块依赖、类关系、系统架构，用LR更直观。两种布局不要混在一张图里，除非你用子图强制分区，否则可读性会大打折扣。
看一个例子：
```mermaid graph TD A[发起审批] --> B{金额是否超过5000?} B -- 否 --> C[直接通过] B -- 是 --> D[上级审批] D --> E{是否同意} E -- 同意 --> C E -- 驳回 --> F[退回申请人] ```这个例子看起来不起眼，但涵盖了Mermaid流程图的五个基础元素：矩形节点（A[发起审批]）、菱形判断节点（B{...}）、普通连线（-->）、带标签连线（B -- 否 --> C）、以及分支汇聚。你把这段代码贴到MPE预览里，马上就能看到一张完整的流程图。
3.2 节点与连线的常用玩法
Mermaid的节点形状跟文本方括号密切相关：
A[文案]：矩形，一般表示操作步骤B{文案}：菱形，一般表示判断/条件分支C(文案)：圆角矩形，一般表示起止状态或温和步骤D[[文案]]：带边框矩形，部分场景表示子系统E[(文案)]：圆柱形，一般表示数据库F{{文案}}：六边形，一般表示准备/预处理
这些形状不是必须严格遵循的规范，但团队内部形成约定后，看图的人能快速建立语义认知。我在写技术文档时，规定所有数据库操作都用圆柱形，所有外部接口调用都用矩形，判断一律菱形。这样一张图拿过来，扫一眼形状就知道哪个节点是数据库操作。
连线的写法也有讲究：
graph TD A[下单] -->|发起支付| B[支付网关] A -->|取消订单| C[结束] B --> D{支付结果} D -- 成功 --> E[发货] D -- 失败 --> F[退款] D -. 通知 .-> G[消息队列]-->|文字|和-- 文字 -->效果几乎一样，注意标点符号必须是英文半角，否则Mermaid解析会报错。虚线用-.->，粗线用==>,你还可以用---表示不带箭头的连接线，这在画拓扑关系图的时候很有用。
3.3 子图与样式：让流程图更接近正式文档
画一周之后你会发现，一个中等规模的流程可能涉及十几个节点。为了避免所有节点平铺在一层，子图（subgraph）就是你的分区利器。
```mermaid flowchart LR subgraph 客户端 A[用户点击] --> B[发送请求] end subgraph 服务端 C[接收请求] --> D[校验参数] D --> E[业务处理] E --> F[写入数据库] end subgraph 外部 G[第三方接口] end B --> C F --> G ```子图的作用不只是视觉分区，它还能让图的层级结构更清晰。当某一天业务方说“这里需要在服务端加一层缓存”，你只需要在服务端子图里加个节点，不会影响其他区域的布局。
样式方面，如果你用的是MPE，可以在mermaid代码块里加%%{init: { "theme": "dark", "themeVariables": { "primaryColor": "#ff9900" } }}%%这样的初始化注解，可以调字体颜色、边框颜色、连线颜色。但我不建议一上来就折腾样式，先把图和内容表达对，样式是锦上添花的事。
3.4 实时预览的完整操作路径
到这里你应该已经能画一张像样的流程图了。我现在梳理一下完整的实时预览操作路径，方便你对照检查：
- 在VSCode里新建文件，命名为
test.md，后缀一定是md。 - 写入 ```mermaid 代码段，代码段里放上面任一示例。
- 按
Ctrl+Shift+V（macOS是Cmd+Shift+V）打开预览。 - 如果你的MPE配置了
offline模式，第一次渲染会提示下载资源，等它完成即可。 - 修改 ```mermaid 代码段保存，预览窗口会在约1秒内自动刷新。
如果你觉得预览窗口的刷新不够及时，检查一下设置里的markdown-preview-enhanced.liveUpdate是否开启。有时候VSCode更新后这个配置会被重置，我遇到过两次，重开开关就好了。
4. 常见报错排查链路：从现象追到根因
这一章是重头戏，我几乎把能踩的坑都踩了一遍，下面按排查链路讲，不讲玄学，讲定位方法。
4.1 预览一片空白：先分清是插件没加载还是语法有问题
遇到预览空白，我现在的第一反应不是改代码，而是先看这块空白是“整个预览窗口空白”还是“代码块变成空白”。这两个现象定位路径完全不同。
如果整个预览窗口白屏，通常是MPE的脚本执行被禁用了，或者插件冲突导致渲染进程崩溃。先按Ctrl+Shift+P，执行Developer: Reload Window，重载后如果还有问题，再看设置里的enableScriptExecution。如果只是某个代码块空白，而页面其余部分正常，那大概率是mermaid代码段语法写崩了，渲染库直接放弃解析。
还有一种容易被忽略的情况：文件不是UTF-8编码。如果你用记事本打开过中文文档再保存成GBK编码，VSCode能辨认但MPE的解析流程可能出问题。解决方案是把所有markdown文件统一为UTF-8。在VSCode右下角状态栏能看到当前文件编码，点击后选择“Save with Encoding”改成UTF-8即可。
4.2 中文字体显示异常：fontFamily配置
你第一次用MPE渲染中文流程图，很可能会遇到这种情形：正文和节点里的文字一个个都是方框或豆腐块，英文正常，中文乱掉。这不是Mermaid不支持中文，而是渲染字体配置里没有可用的中文字体。
解决办法是在mermaid的初始化配置里指定字体族：
```mermaid %%{init: {"theme": "default", "themeVariables": {"fontFamily": "微软雅黑, Microsoft YaHei, PingFang SC, sans-serif"}}}%% graph TD A[发起审批] --> B{金额是否超过5000} B -- 否 --> C[直接通过] ```我用的Windows机器配的是 “微软雅黑, Microsoft YaHei”，Mac上同事配的是 “PingFang SC”。还有一点，如果你导出的PDF里中文依然乱码，那问题往往不在MPE，而在导出引擎缺少对应中文字体。在Windows上装好微软雅黑即可，Linux服务器上需要fonts-noto-cjk这类中文字体包。
4.3 快捷键失效与预览不同步
按Ctrl+Shift+V没反应，或者预览窗格一直不打开，大概率是快捷键被其他插件占用了。VSCode的快捷键冲突非常常见，尤其是装了一大堆插件的人。定位方法是打开Ctrl+K Ctrl+S快捷键设置，搜索 “Markdown: Open Preview to the Side”，看到绑定的按键是否与其他快捷键冲突。如果有重复按键，直接改绑到Ctrl+Shift+Alt+V就好。
预览不同步的问题则是另一回事。MPE默认支持预览与编辑器的滚动同步，但如果你开了多个markdown预览窗口，或者用了分屏编辑，同步会变得时灵时不灵。我的经验是只保留一个预览窗口，把编辑区和预览区并排，不用的时候直接Ctrl+1切回单栏编辑，能减少很多认知负担。
4.4 常见的语法报错：从报错信息判断问题根源
这一节列的报错都是我在实际使用中高频遇到的，配上根因和修复方式，表格更方便查阅。
| 报错现象 | 根因 | 修复方式 |
|---|---|---|
Unable to parse加上一行波浪线指向graph TD | title、方向关键字大小写错误，或代码块开头不是mermaid | 统一小写，确认 ```mermaid 后无多余字符 |
| 节点内文本全部变成乱串 | 标签里用了英文双引号和特殊字符（如#、/、:） | 标签文本外层改单引号，或者给文字加引号，如A["创建/更新"] |
| 图渲染出来了但线条乱连 | 节点文本内含空格或特殊符号，导致ID识别错误 | 给节点ID和标签分开定义，如A1["发起审批"] |
预览窗口底部提示Loading failed | 本地网络受限，MPE试图加载外部资源失败 | 把MPE的资源加载模式切到onLine: false或配置本地缓存，具体看插件版本 |
我一直强调一句话：Mermaid对语法解析是严格模式，它不会像HTML那样容错，写错一个字符整段就废了。解决办法很简单，先复制官方文档里的demo确认环境是好的，再逐步改成你自己的图。如果你是从Word或PDF里粘贴的文案，务必检查引号、括号、冒号、分号全部是英文半角，这是中文输入法留下的老毛病。
4.5 多插件冲突：我踩过的那个“找不到原因”的坑
有一次，我的Mermaid预览突然全部失效，无论怎么写都不渲染。按老办法检查了半天：MPE设置没问题、语法没问题、VSCode也重载了，就是不行。最后我用排除法，把VSCode扩展一个一个禁用，才定位到罪魁祸首——一个名叫“Markdown All in One”的插件，它更新后的某个版本跟MPE的渲染内核冲突，导致mermaid代码块被当作纯文本保留。
这件事给我的经验有两条：
- 排障时不要只盯着Mermaid相关插件，VSCode里所有提供markdown预览能力的插件都可能互相影响。
- 出诡异问题的时候，先禁用最近更新过或者最近安装过的插件，逐个排除。
另外，如果你同时装了Markdown Preview Mermaid Support和MPE，建议只保留MPE，两个插件同时启用容易触发快捷键和渲染的重复逻辑。虽然不至于崩溃，但预览的打开速度会明显变慢。
5. 进阶用法：让Mermaid成为团队协作的一部分
5.1 在Git代码评审里沉淀架构图
Mermaid最大的隐藏价值，是和代码评审深度绑定。当团队建立起“流程图随文档走”的约定后，每个MR里的架构变化、流程变更，会直观地反映在diff里。评审人看Mermaid的文本diff，能清楚地知道这次改动加了什么、删了什么、分支条件发生了什么变化。
我们团队的约定是：所有涉及服务间调用的改动，PR描述里必须有对应的sequenceDiagram时序图；所有涉及状态流转的改动，必须带一张stateDiagram-v2状态图。这个约定坚持半年后，新同学接手老模块的效率明显提升——不再需要口口相传，图就在文档里。
举个例子，一个简洁的时序图：
```mermaid sequenceDiagram participant U as 用户 participant A as 前端 participant B as 后端 U->>A: 点击登录 A->>B: POST /login B-->>A: 返回token A-->>U: 跳转首页 ```这种图写起来非常快，几乎不打断写代码的思路，但表达的信息量比一大段文字描述要清晰得多。
5.2 导出PNG/HTML：从预览到交付
用MPE导出图片是常见的交付需求。MPE内置了puppeteer，可以把预览的markdown导出为PDF、PNG、HTML等格式。操作很简单：在预览窗口右键，选择Export下的Export to ...，格式列表里选你需要的。
如果你要的是单张流程图，而不是整个markdown文档，也有一个常用技巧：在markdown文件里只保留这段mermaid代码块，再导出PNG，就能得到干净的流程图文件。导出的时候建议把Waiting Time调高一点点，避免图还没渲染完就截图导出。
我自己写博客文章时，一般直接把mermaid代码块贴到支持Mermaid的博客平台（比如知乎、CSDN、语雀、Obsidian），本地MPE只是我的预览工具，真正发布时不需要任何导出步骤。如果目标平台不支持Mermaid，则导出PNG贴图。这里一定要记住，导出的PNG是矢量图转换过去的，缩放到A4大小也没问题，前提是导出分辨率选高一些。
5.3 团队统一模板与约定
如果你们团队打算全面铺开用Mermaid，我建议抽时间沉淀三样东西：
- 一个内部风格的markdown文档模板，包含流程图、时序图、状态图的最佳实践，以及节点形状的语义约定关系。
- 一套Mermaid主题变量配置，搭配公司VI色，导出出来的图片能直接放PPT。
- 一份常见报错的内部FAQ，把团队用图期间遇到的坑沉淀下来，新人揉平学习曲线。
这些不花太多时间，但对于维护企业内部的“高质量文档资产”非常有帮助。毕竟，Mermaid写出来的是代码，是代码就该有规范。没有规范的图表仓库，最终也会变成一团乱麻。
我在实际项目中感受最深的是，当你在技术文档里写了流程图，评审的效率会提高很多。以前大家理解偏差靠反复开会，现在一张图放在那里，有问题直接指出来，修改也是一句话的事。这套方案到底值不值得5分钟搭建，答案不言自明。
最后再分享一个小技巧：在VSCode的settings.json里，可以把MPE的启动配置预置为"markdown-preview-enhanced.codeBlockTheme": "dracula.yml"，这样代码块和预览图的配色更统一。至于字体，中文字体优先级始终放在英文字体前面，能避免很多显示上的意外情况。希望你少走我踩过的路，早点把Mermaid加进自己的工作流里。
