VS Code + Mermaid：用代码画图，让文档既清晰又可控

写文档画图这件事我前后折腾过不少工具从Visio到draw.io再到Excalidraw最后稳定在VS Code加Mermaid这套组合上。如果你也整天跟Markdown、接口文档、业务流程图打交道大概率能体会到我的心情——普通文本写不清逻辑关系截图又没法维护而Mermaid这种“用代码画图”的方式刚好把图的表达力和代码的可维护性揉在了一起。这篇文章我把从零配置到进阶实战的完整路径梳理一遍包括插件选型、语法要点、常见坑和处理方案希望能让同样走这条路的你少踩几个雷。1. 为什么把VS Code当成Mermaid的主战场1.1 这套组合到底解决了什么问题先说结论VS Code加Mermaid解决的是“图随文档走”的问题。以前画架构图流程可能是先在Visio里画好再导出图片贴到Word或者Confluence里图一多就乱改一处流程要动一堆文件。而Mermaid是文本化的图表语言写起来跟写Markdown差不多渲染交给工具完成图的每一处改动都可以走代码评审、进Git版本管理。你在VS Code里打开一个.md文件在代码块里写上Mermaid语法装好插件后直接按快捷键就能预览渲染效果。这意味着写接口文档时时序图、流程图、状态图可以和正文放在同一个文件里别人clone下仓库打开就能看到图不需要额外安装桌面软件也不需要上传图片到图床。对团队协作来说这比“一张PNG截图发群里”可维护太多了。很多人会问既然Mermaid官网有Live Editor为什么还要在VS Code里折腾我的看法是Live Editor适合快速验证一段语法但它做不了工程化的事。你没法把它挂到Git钩子里做检查没法在CI里自动导出图片也没法和项目代码放在一起做版本对比。VS Code的价值在于它把编辑器、版本管理、终端、插件生态这些原本分散的能力汇集到一起Mermaid只是其中一个环节。1.2 先认清Mermaid的适用边界Mermaid确实好用但它不是万能的。我做过的项目里它最适合的是以下几类图业务流程图、时序图、状态机图、甘特图、类图、思维导图以及饼图这类轻量统计图。复杂架构图如果节点特别多、连线关系特别密Mermaid的布局引擎生成的图有时会显得拥挤不如draw.io里手动拖拽来得直观。另外要注意的是Mermaid是“文本即图”代码写得乱图也好看不到哪去。它不像Visio那样对每条线都有精细的样式控制字体大小、颜色、连线曲率这些可以调整但精细度比不上专业绘图软件。所以我的判断标准很简单如果一张图超过30个节点或者需要视觉设计感很强的展示效果我会去用draw.io如果是文档里内嵌的流程说明、交互时序Mermaid完全够用。还有一点Mermaid的图表渲染依赖浏览器端的JavaScript实时执行VS Code的预览也是基于这个机制。所以你写的语法最终会被解析成SVG改一处代码图就跟着变省掉了反复截图、替换图片的机械劳动。1.3 适合谁来用后端写接口文档时需要把系统之间的调用关系说清楚前端做组件设计时想画状态流转和组件层级项目经理或产品经理写PRD时用流程图描述业务分支技术博客作者想在Markdown文章里内嵌逻辑图运维同学画部署流程图、定时任务调度甘特图不管你是哪种角色只要你有“把逻辑用图表达”的需求这套东西就值得花半小时熟悉一下。2. 环境准备从零搭建VS Code的Mermaid开发环境2.1 VS Code的下载安装与汉化这一步对老手来说就是几分钟的事但我还是想提几个点因为不少刚入门的同学会卡在这里。VS Code官方渠道下载地址是code.visualstudio.com打开后会自动识别系统选择对应安装包就行。Windows安装时有个地方容易被忽略在“选择其他任务”页面最好勾选“添加到PATH”和“通过Code打开操作”这样后续终端里直接敲code命令就能启动编辑器。装完之后第一件事建议先做汉化不然很多设置项看起来费劲。打开扩展面板搜索“Chinese”找“Chinese (Simplified) (简体中文) Language Pack”作者是Microsoft安装完按提示重启即可。其实插件市场的搜索机制很简单支持模糊匹配你输入中文关键词也能找到对应插件。有个常见现象是打开VS Code扩展面板时一直转圈、加载不出来或者点安装后提示“提取扩展时出错”。这种情况八成是网络没走通VS Code官方扩展市场的域名在国内访问不稳定。遇到这种情况可以临时把代理关掉再重试或者检查DNS设置不推荐用任何绕过网络限制的工具就是正常的网络调试思路换网络、清缓存、重启VS Code一步步排查。2.2 装哪些插件才算配齐Mermaid环境我推荐一个组合覆盖编辑、语法高亮、预览、导出全流程插件名作用是否需要Markdown Preview Mermaid Support在Markdown预览中渲染Mermaid代码块必装Mermaid Markdown Syntax Highlighting为Mermaid代码块提供语法高亮写错颜色会不一样强烈推荐Mermaid Editor提供独立的Mermaid文件编辑、实时预览和导出功能可选但很好用Markdown All in One增强Markdown编辑体验自动完成、列表缩进等推荐装完之后你打开一个.md文件写一段带mermaid标识的代码块调出预览快捷键是CtrlShiftV或者点右上角的预览图标就能看到图渲染出来了。整个过程不需要重启。实际体验中Markdown Preview Mermaid Support是最核心的一个没有它Markdown里的Mermaid代码块只会显示成纯文本。Mermaid Editor则适合处理.mmd这种独立绘图文件它的界面是左代码右预览导出PNG和SVG也方便。2.3 与SSH远程开发等场景的配合VS Code这些年一个很流行的用法是“远程开发”通过Remote-SSH插件连接到服务器在本地窗口里编辑远程文件。这个场景下Mermaid一样能工作只要远程机器上有VS Code Server再把插件装到远程环境中就行。具体操作是先用Remote-SSH连上服务器然后在扩展面板里搜索Mermaid相关插件正常情况下VS Code会提示你“安装到SSH主机”点一下就好。这里有个容易踩的坑如果你只在本地装了插件连接远程后Markdown预览是不会渲染Mermaid的因为VS Code的扩展是区分本地和远程的。检查方法是在扩展列表里看这个插件标注的环境是“本地”还是“SSH”。2.4 顺手解决几个“不相关但总遇到”的小问题不少人在热搜词里搜“vscode右键没有跳转到定义”和“vscode按住ctrl点击方法没跳转”这个虽然跟Mermaid没直接关系但既然配好了环境顺手说两句。跳转失效最常见的原因是装了多个语言插件导致识别混乱或者当前文件类型没有被正确识别。先看右下角的文件语言模式确认是Python、JavaScript还是别的语言不对就手动切换再看是否装了对应语言的扩展比如Python要装Python扩展C要装C/C扩展。还有一个冷知识在Markdown文件里按住Ctrl点击跳转的是标题锚点或链接目标Mermaid代码块里的内容默认不支持跳转。另外设置成中文后插件市场搜索里的描述可能也变成中文找起插件来更直观。3. 核心实操手把手写第一张Mermaid图3.1 在Markdown中嵌入Mermaid的规范写法Mermaid代码块的标准写法是三个反引号加mermaid标识比如mermaid graph LR A[用户] -- B{登录成功?} B --|是| C[进入首页] B --|否| D[提示错误]在VS Code的Markdown预览里这段代码会被渲染成一张从左到右的流程图一个“用户”节点经过一个菱形判断“登录成功?”是则进入“首页”否则提示错误。这里的graph LR表示从左到右布局A、B是节点ID后面中括号里的内容是节点显示文本--表示连线|是|和|否|是连线上的文字。 我见过不少新手一上来就写很复杂的图结果语法报错图渲染不出来然后误以为是工具不行。我的建议是先写一个最小的图确认环境没问题比如graph TD; A--B;能渲染了再往上加东西。 ### 3.2 五种常用图表类型的语法模板 **流程图Graph/Flowchart** 流程图是Mermaid里最常用的类型适合描述业务分支和处理流程。基础语法是节点加连线节点的形状由符号决定中括号是矩形、花括号是菱形、圆括号是圆角矩形、双括号是圆形。线上文字用|文字|标注比如 mermaid graph TD A[开始] -- B{是否注册} B -- 是 -- C[进入主流程] B -- 否 -- D[引导注册] D -- C我一般用graph TD做纵向流程因为中文场景下纵向排布更容易阅读graph LR适合宽度有限的展示区域。注意Mermaid的节点ID不能有空格和特殊字符所以只要显示文本里用中文就没关系ID本身最好用大写字母或英文。时序图Sequence Diagram时序图在接口设计文档里出现频率最高用来表达不同角色或系统之间的消息传递顺序。sequenceDiagram participant A as 客户端 participant B as 服务端 A-B: 发起登录请求 B--A: 返回登录结果 alt 登录成功 A-B: 获取用户信息 else 登录失败 A-B: 提示错误 endparticipant是声明参与者as后面是显示名称。箭头有三种-是实线箭头-是实线带箭头--是虚线带箭头常用于异步返回。alt和else用来画条件分支loop用来画循环这在复杂的交互描述中非常实用。状态图State Diagram状态图适合描述一个对象在不同条件下的状态变化比如订单状态、设备状态。stateDiagram-v2 [*] -- 待支付 待支付 -- 已支付: 支付成功 已支付 -- 已发货: 发货 已发货 -- 已完成: 确认收货 已完成 -- [*][ * ]表示初始状态和结束状态冒号后面是触发条件。stateDiagram-v2是当前推荐版本v1的有些写法在新版Mermaid里已经兼容但可能提示警告直接用v2省心。甘特图Gantt Chart甘特图适合做项目排期Mermaid的甘特图虽然比不上专业项目管理软件精细但放在文档里展示阶段性计划绰绰有余。gantt title 版本迭代计划 dateFormat YYYY-MM-DD section 开发阶段 需求评审 :done, a1, 2025-01-05, 3d 编码开发 :active, a2, 2025-01-08, 10d 测试阶段 :a3, after a2, 5dsection是分组done表示完成状态active表示进行中日期可以用具体日期也可以用after相对前一个任务来排。思维导图Mindmap思维导图是Mermaid 9.7之后加入的用来梳理知识结构太方便了。mindmap root(项目文档) 需求文档 用户故事 验收标准 技术方案 架构设计 数据模型 测试报告 功能测试 性能测试3.3 用Mermaid Live Editor做快速验证VS Code里写了几行语法但预览一直报错时我习惯把代码复制到Mermaid官网的Live Editor里跑一下。Live Editor的界面左边是代码右边实时渲染底部还有控制台输出错误信息。那里面的报错比VS Code插件报错有时更详细特别方便定位括号不匹配、引号缺失这类低级错误。Live Editor在线地址是mermaid.live不用安装任何东西。它的另一个用途是把调好的图直接导出为PNG或SVG处理快速提案、临时演示这类轻量场景足够。不过正式文档里的图我还是建议留在Markdown源码里维护而不是导出成图片贴上去否则又回到了“图片改不动”的老路上。3.4 写语法时我总结的几条铁律节点文本里尽量别用特殊字符比如()、[]、{}这些是语法保留符号非要显示的话一定要把文本用双引号包起来。中文字体在默认预览里可能偏小如果追求好看可以通过style或主题调整。同一个图不要又用中文又用英文做节点ID时间长了你自己都会乱。代码块语言标识一定是小写的mermaid写成Mermaid或mermaid之外的都会导致无法渲染。4. 进阶玩法把Mermaid的潜力彻底用起来4.1 配置自定义样式与主题Mermaid支持通过%%{init: {...}}%%开头的指令来配置主题和样式。比如最常见的深色背景适配问题在浅色主题下渲染的图整体偏灰浅放进深色博客里会很突兀可以在代码块开头加一行%%{init: {theme: dark} }%% graph TD A[开始] -- B[处理]也可以直接调整主题变量比如背景色、连线颜色、字体大小。这个配置对整张图生效省去了逐个节点加样式的工作量。但要注意配置指令必须放在代码块的最顶部前面不能有其他内容。4.2 导出PNG和SVG的正确姿势VS Code里Mermaid的导出有两个方向一是用Mermaid Editor插件它自带导出按钮支持PNG、SVG二是直接把预览页面的渲染结果另存为。更工程化的方式是用命令行工具比如mermaid-js/mermaid-cli配合mmdc命令一键导出。这招适合在CI流程里用写好脚本后每次文档更新都能自动生成图片附件。npm install -g mermaid-js/mermaid-cli mmdc -i input.mmd -o output.svg mmdc -i input.mmd -o output.png -t dark -w 1200-t dark指定主题-w指定宽度像素。不过命令行工具依赖puppeteer去调浏览器渲染第一次跑会下载Chromium需要点耐心。如果你只需要导出一两张图直接用Mermaid Editor插件更省事。4.3 用VitePress把自己笔记变成文档站如果你写了一套带Mermaid的Markdown笔记想生成一个漂亮的文档站VitePress是很顺手的方案。它天然支持Markdown通过插件在代码块渲染阶段把Mermaid转成HTML。在VitePress里配Mermaid需要在.vuepress或.vitepress目录下写一个小插件思路是在页面加载后扫描所有mermaid代码块再调用mermaid.render()函数一个个渲染。网上有人封装好了现成的组件搜vitepress-plugin-mermaid就能找到。配好之后你的Markdown笔记就能变成一个带目录、带搜索、带风格主题的文档站Mermaid图全部内嵌渲染效果非常舒服。4.4 Mermaid和draw.io、飞书的互通问题热搜里有个问题“drawio可以mermaid吗”我顺手讲清楚。draw.io和Mermaid是两套不同的文件格式体系draw.io用XML格式存储图形Mermaid只能靠文本代码描述生成内容官方并没有双向互导入导出的功能。如果你要用draw.io打开Mermaid内容只能先渲染成SVG或PNG再导入反过来想把draw.io的图变成Mermaid文本基本只能照着原图重画没有捷径。另一个高频问题是在飞书文档里写Markdown代码块里的mermaid不渲染。飞书目前的Markdown解析对Mermaid的支持并不完善文档里写明“Mermaid流程图”也经常只显示成代码文本。目前常见的解法是把图导出成图片再上传或者用支持的集成工具转换。这个属于平台限制不是Mermaid或VS Code能解决的。4.5 搭配Git做团队协作的流程建议团队协作时Mermaid最大的红利在于“图能走代码审查流程”。我所在的团队现在约定架构图、流程图全部用Mermaid写在Markdown的docs目录下改图要提PR评审时图的变化一目了然。有冲突时Git也能把改动展示出来这比在共享网盘里放一张图你改我改最后谁也说不清要好太多。实践中还有一个细节如果团队成员用的是不同平台导出图片时要统一格式和分辨率。一般建议SVG因为它是矢量图缩放不失真放进PPT或者网页里都方便。5. 高频问题排查实录代码写对了图还是不出来5.1 图表完全不渲染或渲染成纯文本这是最常见的情况原因通常是插件没装生效或文件关联错误。第一步看右下角当前文件是不是被识别为Markdown如果是Plain Text预览里自然不解析Mermaid。第二步点开扩展列表确认Markdown Preview Mermaid Support已启用没启用就重新加载窗口。第三步看代码块的围栏语言是不是精确到小写mermaid大写了不行。5.2 渲染一半提示“Syntax error in text”这种错误说明你的Mermaid语法有不符合规范的地方。常见原因有节点ID使用了保留字符、连线上文字没加引号、括号没有闭合、中文标点混入了代码区域。我的排查习惯是把代码块内容整体复制到Live Editor里它会给出更具体的错误行号。基本上语法错误都集中在“多打了一个括号”“少写了一个引号”这些细节上。5.3 插件的下载安装总是失败VS Code扩展一直下载失败有一个临时招式是修改“设置”里的extensions.autoCheckUpdates或者手动下载VSIX文件后通过“从VSIX安装”。这个方式在部分网络环境下特别有效。另外“提取扩展时出错”通常发生在Windows下压缩包解压环节把VS Code的安装目录或用户目录加入杀毒软件信任区一般能解决。提示手动装VSIX前要看版本兼容性Mermaid插件一般要求VS Code 1.60以上太老的编辑器版本装不上新版插件。5.4 预览正常导出图片时中文乱码中文乱码的根源是字体缺失命令行导出时尤其明显。解决方案是给mmdc命令指定中文字体或者安装fonts-noto-cjk之类的字体包。如果是Windows系统确保系统里有微软雅黑然后在命令里加上mmdc -i input.mmd -o output.svg -f -c config.json在config.json里指定fontFamily: Microsoft YaHei导出图片里的中文就正常了。5.5 远程开发时预览不生效如果通过SSH连远程服务器本地预览不渲染Mermaid记住一句话插件要装到远程环境里。在扩展面板搜索插件后点安装按钮旁边的小下拉箭头选择“安装到SSH主机”装完后重新加载远程窗口。还有一点远程环境的VS Code Server版本会自动匹配但插件版本可能滞后必要时手动在远程终端里执行code --install-extension安装指定版本。6. 我踩过几次坑之后的一些实际操作心得手写Mermaid图到现在我最大的体会是写图跟写代码一样要把“可读性”放在第一位。节点ID用有意义的英文或拼音缩写文字语义清晰分组和注释该加就加。Mermaid是能写注释的格式是%% 注释内容放在代码里不会影响渲染。我画复杂的流程图时一定会写注释不然过了两周自己回来看代码都认不出节点含义更别说同事。另外团队协作时最好约定几种固定模板。比如接口时序图统一用sequenceDiagram业务流程用flowchart TD状态流转用stateDiagram-v2。模板固定了不同人写的Mermaid代码风格才能统一review起来也快。我还会在项目根目录放一个docs/mermaid-examples.md把团队常用的几种图模板和写法沉淀在里面新人来了看一遍就能上手。最后再分享一个收尾的小技巧Mermaid渲染出来的图是矢量SVG在网页里放大缩小都清晰但如果你要放进Word文档或PPT记得先转成位图PNG再贴否则对方电脑上可能因为缺少渲染组件显示空白。导出图片时宽度统一设成不要超过1200px放到文档里排版更稳。说实话从“用画图工具手动拖拽画流程”过渡到“用Mermaid代码维护一张图”前几次会有点不习惯但用顺了之后真的回不去。特别是Git能记录图的每一次改动团队评审时能看见具体哪条线、哪个节点发生了变化这种体验是传统绘图工具完全给不了的。如果手头正有一批文档要画图不妨从今天开始用VS Code建一个带Mermaid的Markdown文件试试看。