上周三晚上十一点我在微信群里把新项目的模块依赖图发出去同事回了一句“这图你是用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文件里。代码评审的时候图跟代码放在同一个MRMerge Request里评审人不用跳转到外部系统看图修改意见直接指向文档的某一行提交记录里能看到这张图是在哪个版本加了哪个分支。这些东西传统拖拽式工具无论如何都给不了。另外Mermaid的图不是静态图片它支持用户交互。节点上可以挂点击跳转链接可以配置tooltip某些场景下还能嵌进HTML和Vue组件里。我在做内部系统的时候就把接口调用的时序图直接渲染到前端的帮助文档页面里运维同事点开某条时序图就能看到每个步骤对应的日志关键字排查问题不再需要翻wiki。1.3 哪些人最适合用这套方案如果你符合以下任何一条我都建议你把Mermaid用起来写技术方案、接口文档、系统设计文档需要经常插入流程图的研发、测试、运维工程师做产品原型说明、需求文档需要表达用户路径和状态流转的产品经理、交互设计师写课程讲义、实验指导书需要大量示意图的教师、培训讲师写公众号、知乎、博客经常用流程图辅助讲解的技术写作者这套方案的下限很低装个插件就能用上限也不算低配合自定义主题、子图、图表混排能做出接近专业绘图软件的效果。最关键的是整个环境开箱即用基本不依赖外网服务离线环境也稳定。2. 5分钟搭好实时预览环境选插件的门道都在这里2.1 VSCode安装与基础准备大多数写代码的人机器上已经有VSCode了但为了不跳过任何步骤我还是提一嘴。官方安装包从官网下载安装时建议勾选“添加到PATH”和“通过Code打开操作”这两个选项。虽然Mermaid预览不依赖PATH但装了之后方便你在终端里直接用code 某个文件打开项目属于高频小便利。VSCode装好后建议先把中文语言包装上。虽然Mermaid语法和插件界面都是英文但VSCode的中文设置会让你在建工作区、修配置文件的时候更不容易出错。打开扩展面板CtrlShiftX搜索“Chinese Language Pack”安装后按右下角提示重启即可。2.2 插件选型我踩过的对比清单VSCode里跟Mermaid相关的插件少说也有七八个我几乎都试过最后留下了两个主力各有分工。插件名核心能力适用场景备注Markdown Preview EnhancedMarkdown增强预览内置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[跳转注册页] 然后按CtrlShiftV打开预览。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 Downgraph 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 代码段代码段里放上面任一示例。按CtrlShiftVmacOS是CmdShiftV打开预览。如果你的MPE配置了offline模式第一次渲染会提示下载资源等它完成即可。修改 mermaid 代码段保存预览窗口会在约1秒内自动刷新。如果你觉得预览窗口的刷新不够及时检查一下设置里的markdown-preview-enhanced.liveUpdate是否开启。有时候VSCode更新后这个配置会被重置我遇到过两次重开开关就好了。4. 常见报错排查链路从现象追到根因这一章是重头戏我几乎把能踩的坑都踩了一遍下面按排查链路讲不讲玄学讲定位方法。4.1 预览一片空白先分清是插件没加载还是语法有问题遇到预览空白我现在的第一反应不是改代码而是先看这块空白是“整个预览窗口空白”还是“代码块变成空白”。这两个现象定位路径完全不同。如果整个预览窗口白屏通常是MPE的脚本执行被禁用了或者插件冲突导致渲染进程崩溃。先按CtrlShiftP执行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 快捷键失效与预览不同步按CtrlShiftV没反应或者预览窗格一直不打开大概率是快捷键被其他插件占用了。VSCode的快捷键冲突非常常见尤其是装了一大堆插件的人。定位方法是打开CtrlK CtrlS快捷键设置搜索 “Markdown: Open Preview to the Side”看到绑定的按键是否与其他快捷键冲突。如果有重复按键直接改绑到CtrlShiftAltV就好。预览不同步的问题则是另一回事。MPE默认支持预览与编辑器的滚动同步但如果你开了多个markdown预览窗口或者用了分屏编辑同步会变得时灵时不灵。我的经验是只保留一个预览窗口把编辑区和预览区并排不用的时候直接Ctrl1切回单栏编辑能减少很多认知负担。4.4 常见的语法报错从报错信息判断问题根源这一节列的报错都是我在实际使用中高频遇到的配上根因和修复方式表格更方便查阅。报错现象根因修复方式Unable to parse加上一行波浪线指向graph TDtitle、方向关键字大小写错误或代码块开头不是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加进自己的工作流里。