前阵子有个同事问我你们技术方案里的架构图、时序图都用什么画我说 Mermaid直接在 VSCode 里写。他一脸疑惑反手甩给我一堆热搜关键词vscode mermaid、mermaid live editor、markdown preview mermaid support。他说大家搜来搜去不就是想解决“在 VSCode 里用 Mermaid 画图”这件事吗确实很多人知道 Mermaid 这个名字也听说过 VSCode 装个插件就能预览但真到了自己动手配置、写语法、遇到渲染问题的时候还是会被各种小细节卡住。今天我就把自己这一两年在 VSCode 里写 Mermaid 的插件组合、常用语法、批量导出、踩坑记录和团队协作习惯完整地摊开来聊一遍。适合所有想在 Markdown 文档里嵌入流程图、时序图、甘特图又不想被在线工具绑架的开发者。1. 为什么我放弃了在线流程图工具改用 VSCode 写 Mermaid1.1 在线编辑器看起来很香但一协作就露馅早几年我用在线流程图工具也挺顺手拖拽画框、连线、改颜色看起来“所见即所得”。但真到多人协作的项目里问题就开始扎堆同事改了图我这边看不到改动记录评审意见只能靠截图加红框想回退到上一版发现历史版本被锁在付费功能里。最痛苦的是图和代码存在于两个世界代码改了一版图还是老样子过两周自己都分不清哪张图对应哪个版本的逻辑。后来我意识到对于写代码的人来说图的本质不是“画出来的作品”而是“对系统逻辑的表达”。只要这个表达能变成文本它就能进 Git能被 diff能被 review能被注释能跟着代码一起演进。这就是 Mermaid 最打动我的地方它把一个流程图写成类似 Markdown 的纯文本然后用 JavaScript 渲染成 SVG 或 PNG。既然我已经整天泡在 VSCode 里写 Markdown那图也应该在这同一个地方解决。1.2 VSCode Mermaid 的本质把图当成代码来管理有人会说在线编辑器我也能导出代码也能保存。问题在于“顺手”。在 VSCode 里写 Mermaid最核心的体验不是省一个网页标签页而是整个工作流被统一了图和 Markdown 文档放在一起不需要切软件语法高亮、自动补全、代码折叠都套用编辑器能力保存文件后预览实时刷新光标定位到某一行预览里能快速对应改动走 Git 流程评审人在 PR 里直接看 Mermaid 源码比看一张压缩过的小图片清楚得多需要交付 PNG/SVG 时用 mermaid-cli 一条命令批量导出不需要人肉截图。所以这篇文章不止是讲“怎么装插件”更想讲清楚一套能够长期用的工作流插件怎么选、语法怎么写、导出怎么做、出了问题怎么排。2. 环境准备VSCode 插件选型与离线渲染方案2.1 一套够用且不打架的插件组合我先直接给结论日常写 Mermaid我装的插件就三个必要时再加一个 Markdown Preview Enhanced。不要一口气装五六个同类插件预览引擎会互相干扰到时候报错都不知道该怪谁。插件名插件 ID作用我的评价Markdown Preview Mermaid Supportbierner.markdown-mermaid在 Markdown 预览中渲染 mermaid 代码块必装最轻量Mermaid Markdown Syntax Highlightingbpruitt-goddard.mermaid-markdown-syntax-highlighting给 mermaid 代码块做语法高亮强烈建议写代码更省眼Markdown All in Oneyzhang.markdown-all-in-one目录、快捷键、表格格式化属于 Markdown 写作标配Markdown Preview Enhancedshd101wyy.markdown-preview-enhanced增强预览支持导出 HTML/PDF可选想要一键导出时再装安装方式没什么可说的打开扩展商店搜名字点安装然后重启窗口。需要注意的是如果你同时装了 Markdown Preview Mermaid Support 和 Markdown Preview Enhanced两个扩展都会尝试接管预览偶尔会出现“代码块渲染两次”或者“预览空白”的情况。我自己习惯是用前者做日常预览用后者做最终导出两者同时启用但把 Preview Enhanced 的自定义主题关掉避免样式冲突。2.2 用 mermaid-cli 把图导出成 PNG/SVGVSCode 里的预览只能在编辑器里看真要交付到文档、PPT 或公众号里还是得有静态图片。mermaid-cli 是官方提供的命令行工具底层调用 Puppeteer 启动 Chromium 去渲染页面再截成图片或矢量图。安装很简单前提是你机器上已经有 Node.jsnpm install -g mermaid-js/mermaid-cli安装完就能用了。先写一个测试用的.mmd文件内容就是普通的 Mermaid 语法flowchart LR A[写代码] -- B[执行 mmdc] B -- C[得到图片]然后在终端执行mmdc -i test.mmd -o test.svg mmdc -i test.mmd -o test.png -w 2048-w参数是输出宽度建议导出 PNG 时把它设置成 2048 或更大不然放到文档里会模糊。第一次运行时 mmdc 会下载一个精简版 Chromium如果网络条件不好这一步会卡很久甚至失败。解决办法是让 Puppeteer 直接使用你本机已经装好的 Chrome/EdgePUPPETEER_EXECUTABLE_PATHC:/Program Files/Google/Chrome/Application/chrome.exe mmdc -i test.mmd -o test.pngWindows 用 set 命令设置环境变量macOS/Linux 在命令前直接加即可。2.3 把 VSCode 调成“一边写一边看”的布局Mermaid 在 VSCode 里最舒服的用法就是左半边是 Markdown 源码右半边是实时预览。打开方式很简单打开.md文件按Cmd Shift PWindows 是Ctrl Shift P输入 “Markdown: Open Preview to the Side”回车预览面板会出现在右侧光标在源码里定位到 mermaid 代码块预览也会跟着走。如果你是经常写技术文档的人建议把预览面板固定住不要每次重新打开。再配合 VSCode 的自动保存每次改动语法都能立刻看到结果这比去 mermaid.live 复制粘贴再截图爽多了。顺带一提mermaid.live 也不是没用我通常是拿它做临时调试用的——比如 VSCode 预览报错又看不出来具体位置时把代码粘过去看官方的报错提示。3. Mermaid 核心语法可以直接复制的示例3.1 流程图 flowchart使用频率最高的一张图几乎所有刚接触 Mermaid 的人第一张图都是流程图。流程图的写法非常直观节点用中括号包起来箭头用--方向用关键词标注比如TD表示从上到下LR表示从左到右。flowchart TD A[开始] -- B{已经装好 Mermaid 插件了吗} B -- 否 -- C[在扩展商店搜索并安装] C -- D[重载窗口] B -- 是 -- E[写 mermaid 代码块] D -- E E -- F[打开 Markdown 预览查看结果]这段代码里B{...}是菱形判断节点-- 否 --是带文字的边。如果你想把判断条件写得更清晰也可以把整段边上的文字用引号包起来flowchart LR A[收到需求] -- B{有没有现成接口} B -- 有 -- C[直接接入] B -- 没有 -- D[评估开发量] D -- E{开发量可接受?} E -- 是 -- F[排期开发] E -- 否 -- G[反馈给产品]说实话流程图并不需要把所有分支都画得特别复杂我见过很多人把一个流程图画成十几层嵌套结果自己看着都晕。Mermaid 的好处是改起来快所以你完全可以保持“主路径清晰、异常分支单独成段”的写法。3.2 时序图 sequenceDiagram接口对接和流程沟通神器时序图是我在技术方案评审中使用频率最高的一种图因为它能非常清楚地表达“谁在什么时候调了谁的什么方法”。sequenceDiagram participant U as 用户 participant FE as 前端页面 participant SVC as 后端服务 participant DB as 数据库 U-FE: 输入账号密码 FE-SVC: POST /api/login SVC-DB: 查询用户信息 DB--SVC: 返回用户记录 SVC--FE: 返回 token FE--U: 登录成功语法要点说几个participant A as 别名可以让你在代码里用简短名字而图上显示完整名称-是实线带箭头--是虚线带箭头可以用activate和deactivate把时序图里“方法正在执行”的过程标记出来比如sequenceDiagram participant CLIENT as 客户端 participant API as 网关 participant ORDER as 订单服务 CLIENT-API: 创建订单 activate API API-ORDER: 调用订单接口 activate ORDER ORDER--API: 返回订单号 deactivate ORDER API--CLIENT: 返回成功 deactivate API时序图在接口对接时特别好用因为一张图就能把前后端、第三方服务、数据库之间的调用关系说清楚比坐在会议室里拿画笔在板子上比划高效得多。3.3 甘特图与饼图汇报占大头时靠它救场甘特图是我推荐所有项目经理和小组长必学的 Mermaid 图。它的语法核心是定义任务名、状态、时间点和持续时间gantt title 前端版本发布计划 dateFormat YYYY-MM-DD section 开发阶段 需求梳理 :done, a1, 2025-01-06, 2d 组件开发 :active, a2, after a1, 4d 接口联调 :a3, after a2, 3d section 测试阶段 功能测试 :a4, after a3, 2d 回归测试 :after a4, 1ddateFormat用来定义日期格式after a1表示该任务在前一个任务之后开始。任务状态用done、active、crit标记甘特图上会自动显示颜色和进度条。饼图就更简单了适合展示占比关系pie title 团队本周工时占比 产品需求 : 25 技术方案 : 20 编码开发 : 35 测试修复 : 15 会议沟通 : 5饼图虽然最简单但占比数据稍稍一变就要重开在线工具复制数据再截图用 Mermaid 的话改一个数字刷新即出图。这也是“图表即代码”最直观的体验。3.4 子图 subgraph复杂系统图的基本组织单元画系统架构图时最怕把所有节点堆在一个大画布里连线和文字缠在一起。Mermaid 的subgraph可以把相关节点圈进一个分组相当于给图分了个层。flowchart LR subgraph FE[前端应用] page[页面组件] -- api[API 封装层] api -- request[HTTP 请求] end subgraph BE[后端服务] gateway[网关] -- auth[认证模块] auth -- business[业务服务] end request -- gateway这样前端、后端各自一层跨层只留一条主线阅读体验会好很多。我还习惯在 subgraph 名称里用中文别名像subgraph FE[前端应用]这样代码里用英文标识符图上展示中文既方便命令操作也不影响阅读。4. 从“能画”到“画得规范”主题定制与项目级复用4.1 用 init 指令统一主题与品牌色Mermaid 默认的配色是浅色背景加蓝绿色节点临时看看没问题但放到公司文档里气质总差一截。Mermaid 提供了配置指令可以在代码块第一行设置主题和自定义颜色%%{init: {theme: base, themeVariables: {primaryColor: #f0f3f8, lineColor: #556677, textColor: #223344}}}%% flowchart LR A[统一风格] -- B[团队文档] B -- C[视觉协调]常用主题有default、base、dark、forest、neutral。如果只是自己调试直接在 mermaid.live 的主题下拉框里切着预览如果是要统一输出建议把 init 配置固定成一个模板复制到所有文档开头。这里有个细节值得提醒init 指令必须放在 mermaid 代码块的第一行前面不能有空格不然部分渲染引擎会把它当成普通注释忽略掉导致主题不生效。4.2 用 .mmd 文件管理全项目图表配合脚本批量导出很多人都把 Mermaid 直接嵌在.md文档里这没问题。但当一个项目里的图越来越多我建议把图单独拆成.mmd文件统一放在docs/diagrams目录下然后用脚本批量导出。目录结构大概是这样的docs/ ├── README.md └── diagrams/ ├── auth-flow.mmd ├── order-sequence.mmd └── release-gantt.mmd在 Linux/macOS 下一行 for 循环就能把整个目录导出成图片mkdir -p docs/images for f in docs/diagrams/*.mmd; do mmdc -i $f -o docs/images/$(basename $f .mmd).svg -b transparent done-b transparent表示导出透明背景这样图片放进浅色或者深色文档里都不会留个白色方块。再进一步你还可以把这段命令写进package.json的 scripts 里{ scripts: { diagrams: for f in docs/diagrams/*.mmd; do mmdc -i \$f\ -o \docs/images/$(basename \$f\ .mmd).svg\ -b transparent; done } }之后团队统一跑npm run diagrams就能重新生成所有图不用谁再去手动截图。这也是我最推荐团队使用的方式源文件入库图片可再生成。4.3 Markdown 里嵌 Mermaid 的几个隐藏约定这里有几个我踩过坑后总结的约定Mermaid 代码块必须用围栏式代码块标记语言是mermaid三个反引号后直接跟mermaid不要加多余空格一个代码块里只能有一个图定义。如果你想在一篇文档里画三个图就写三个独立的 mermaid 代码块不能把 mermaid 代码块嵌套在其他列表项里缩进超过一定层级否则 Markdown 解析器可能把它当成纯文本如果你用的是旧版 VSCode 或旧版 Windows 自带记事本编辑的文档注意中文标点不要混进语法里。最经典的报错就是把中文括号写成了节点语法里的英文括号()。这些约定看起来很基础但我在帮同事排查问题时十次有八次都是这类原因。5. 我们实测踩过的坑渲染失败、乱码、版本不一致5.1 预览空白或报错时的标准排查顺序Mermaid 预览出问题通常有三种表现预览区完全空白、显示红框错误信息、或者代码原样展示而不是渲染成图。我的排查顺序是这样第一步看代码块语言标记是不是mermaid记住是小写。写成了Mermaid或者mmd部分插件就是不理你。第二步看插件有没有被禁用。打开扩展面板搜索 Markdown Preview Mermaid Support确认状态是“启用”。插件装好之后如果没生效按CtrlShiftP输入 “Developer: Reload Window” 重载一次窗口。第三步把 mermaid 代码复制到 mermaid.live 的左侧编辑区。live editor 的报错机制比 VSCode 插件更直观它会用黄色波浪线标出问题行。大部分语法错误括号不匹配、引号缺失、方向关键字写错都能在 live editor 里秒级暴露。第四步检查文档中是否存在多个同名节点或重复边定义。Mermaid 对边和节点的冲突处理比较宽容但部分版本会出现“一张图里有两条一模一样的边导致渲染方向混乱”的情况。还有一个小技巧如果整个 Markdown 预览打不开别急着怀疑 Mermaid先看看普通文字能不能正常显示。有时候是 Markdown Preview Enhanced 的自定义样式写坏了禁用该插件再试一次。5.2 中文变成方块的真正原因和解决办法在 VSCode 的预览里Mermaid 中文通常没问题因为预览走的是本地浏览器的字体渲染。但用 mermaid-cli 导出 PNG/SVG 时中文变成方块的概率就非常高。原因不是 Mermaid 不支持中文而是 Puppeteer 启动的精简 Chromium 里没有安装中文字体渲染时找不到对应字形。解决办法有两个方向第一个方向给 mmdc 指定一个系统已有的中文字体配置文件。新建一个mermaid-config.json{ fontFamily: Microsoft YaHei, PingFang SC, Noto Sans CJK SC, sans-serif }然后执行mmdc -c mermaid-config.json -i docs/diagrams/auth-flow.mmd -o docs/images/auth-flow.svg第二个方向Windows 上如果系统中已经装了微软雅黑但导出还是乱码可以检查一下环境变量PUPPETEER_EXECUTABLE_PATH是否指向了你日常使用的 Chrome/Edge。使用完整版浏览器渲染时字体加载通常比精简版 Chromium 更可靠。另外提醒一句SVG 文件里如果引用了本地字体拷贝到别的机器上可能因为缺字体而显示不对。最稳妥的做法是导出 PNG 用于外部文档SVG 只在网页场景中使用。5.3 VSCode 插件里的 Mermaid 版本落后于官网Mermaid 语言迭代速度不慢新增了block-beta、quadrantChart等新图型。你明明在 mermaid.live 上跑得好好的回到 VSCode 预览却报“unknown diagram type”这时候基本可以断定是插件内置的 Mermaid 版本太旧。解决办法就是升级插件。在扩展市场里搜索 Markdown Preview Mermaid Support如果有更新直接点 Update。更新后如果还不行再重载一次窗口。VSCode 插件本质上是在本地调用了 Mermaid 的 JS 库扩展作者不更新你就没办法使用新语法。所以遇到版本问题别硬调代码先更新插件。5.4 Windows 环境下 npm 安装和路径的小麻烦Windows 上使用 mermaid-cli 最常见的两个问题一个是 npm 全局安装权限另一个是路径包含空格。npm 全局安装如果报 EACCES 或权限错误多半是 Node.js 安装时没有配置好全局目录。用管理员身份打开终端再执行安装能解决但我更推荐用 nvm-windows 管理 Node.js 版本这样全局包都装在用户目录下不需要管理员权限。路径含空格的问题主要出现在 mmdc 参数上。比如你的项目路径是D:/My Project/docs/diagrams命令行里没加引号解析就会出错。按前面那种for循环写法用双引号包住$f和输出路径能避掉绝大多数问题。6. 在实际项目里我是怎么用的技术方案评审与团队规范6.1 一次技术评审里的完整示例拿一次真实的登录授权方案评审举例。我通常会在方案文档开头放一张 Mermaid 流程图然后用时序图描述具体请求流程。你可以直接参考这个结构flowchart TD A[用户访问业务页面] -- B{本地是否已有token} B -- 有 -- C{token是否过期} C -- 否 -- D[携带token访问接口] C -- 是 -- E[调用刷新token接口] E -- F{刷新是否成功} F -- 成功 -- D F -- 失败 -- G[跳转登录页] B -- 没有 -- G D -- H[返回业务数据]评审时参会者可以一边看这张图一边对照代码逻辑提问。因为 Mermaid 源码就在文档里任何人有疑问可以直接在评论区指出“第几行节点对应哪段代码”比在图片上画红色箭头要精确得多。这也是我坚持在技术方案里用 Mermaid 而不是纯图片的理由评审本身就是一次 code review图也是代码的一部分。6.2 团队约法三章源文件、导出文件与命名规范用了大半年之后我和团队定了一套简单的规范分享出来供参考所有 Mermaid 源文件统一放docs/diagrams不直接散落在根目录导出的图片统一放docs/images命名和源文件保持一致比如auth-flow.mmd对应auth-flow.svg.mmd文件提交到仓库导出的.png要不要提交看情况。如果图片只是发布用的可以加进.gitignore需要用的时候跑一次npm run diagrams每张图的标题用%% 注释写在文件顶部说明这张图什么时候加的、给谁看、对应哪个需求。Mermaid 支持百分号注释这是很多人忽略的好功能命名建议用功能名不要用final2_reallyfinal_v3.mmd一旦图和代码一样需要长期维护“v3”这种后缀只会制造混乱。另外我强烈建议把 mermaid 代码块写进 VSCode 的用户代码片段里。新建一个 Markdown 代码片段{ Mermaid Block: { prefix: mmd, body: mermaid\n$0\n } }以后在 Markdown 里输入mmd再按 Tab代码块就直接出来了。别小看这个习惯我写文档时几乎每天都会触发几十次。6.3 我现在的例行工作流现在我的日常已经固定成一套动作在docs/diagrams里直接新建.mmd文件写到一半打开 VSCode 右侧预览确认布局写完后在README.md里用 Markdown 语法把图嵌进去提交 PR 前跑一次npm run diagrams导出新图片。代码改、图就改图改、文档重新生成。如果你现在还在各种在线画图工具之间反复横跳我真心建议花一个下午把本文里的示例都敲一遍。装插件五分鐘学语法一个钟头剩下的就是每天省下的大量截图、上传、粘贴和对齐时间。Mermaid 不是万能的并不适合做像素级好看的 UI 稿或复杂拓扑图但在“技术方案、接口说明、架构梳理”这些日常场景里它已经足够能干而且能干很久。