画图这件事是每个写文档的人都绕不开的坎。我之前给项目补一份接口文档里面要画一个下单支付的流程打开ProcessOn新建拖节点连箭头……折腾二十分钟图是画出来了可第二天产品经理说逻辑改一下我又得重新拖一遍连线的角度还得调半天整个人都麻了。后来换了Mermaid配合VSCode插件做流程图实时预览这类场景基本被根治了左侧写几行文本右侧图表立刻刷新改逻辑就改字图的样式完全不会乱。如果你还没接触过Mermaid我给你一句话解释它是一种用纯文本描述图表的语法把流程、时序、甘特、状态这些内容写成类似代码的文本再由渲染器生成真正的图形。你不需要记住每个细节只需要掌握最常用的一小部分语法就能在VSCode里画出能放进技术方案、毕业设计和项目汇报里的流程图。这篇内容我会把VSCode插件选型、5分钟搭好实时预览环境、常用语法写法以及我实际踩过的报错和排查方法一次性讲清楚。文章不要求你有很强的编程基础只要电脑上装好了VSCode跟着一步一步走就能跑起来。想少走弯路的话建议不要跳过第4节报错排查那部分都是我拿真实经历换来的。1. Mermaid是什么为什么我的流程图方案从拖拽改成了写代码1.1 Mermaid不止能画流程图这些图都能用文本生成很多人一提到Mermaid就只想到流程图其实它支持的类型比想象中多。我日常用得最多的是graph流程图和sequenceDiagram时序图但偶尔也会用gantt甘特图排一下项目计划用stateDiagram-v2状态图画接口的状态流转用classDiagram类图描述核心模块关系。这些图表有一个共同特点全部由文本节点和连线组成没有手动拖拽的物理坐标。你写一个A -- B它就从A连到B你换一行写A -- C新的分支自然出现。我最早被Mermaid吸引就是因为它符合程序员“代码即一切”的习惯图和代码可以一起提交到Git仓库需求变了直接改文本而不是在一堆图形元素里找线条。另外Mermaid还支持pie饼图、mindmap思维导图、journey用户旅程图等。你要是平时做项目规划、写产品文档这些类型也都能用上。学习曲线并不陡流程图语法半小时能入门时序图和甘特图各自再花十几分钟看一遍示例基本就能上手。1.2 对比一圈之后为什么我最终留在VSCode我刚接触Mermaid时试过Mermaid官方提供的Live Editor在线编辑器也用Typora写过带Mermaid的Markdown文档还用过draw.io这类拖拽工具。这几类方案各有各的处境我用一张表给你看清楚方案优点缺点Mermaid Live Editor打开网页就能用即时渲染不适合多人协作代码和文档分离改图要重新粘贴Typora写作体验好本地文件可管理新版依赖授权老版本对部分新语法支持差draw.io / ProcessOn拖拽直观样式丰富改图成本高部分功能有会员限制图无法做到文本化diffVSCode 插件免费开源和代码一起提交支持diff导出格式多首次配置插件需要一点学习成本这轮对比下来VSCode方案最大的优势不是单一功能最强而是它把所有工作放到同一个环境里。我写代码用VSCode写Markdown用VSCode画图也用VSCode文档里的图可以直接引用本地md文件里的Mermaid代码不需要导出图片上传到文档系统改起来特别顺。1.3 这套方案真正解决了我哪些痛点第一个痛点是版本管理。用拖拽工具生成的图片本质上是一张静态图需求改了旧图就作废了。Mermaid源码是文本文件丢进Git仓库里谁改过、改了什么都清清楚楚代码review时也能直接看到流程变化这是我最满意的一点。第二个痛点是协作成本。同事拿到一个md文件装上插件打开就能看到图不需要单独安装Visio也不需要一个一个发图片。新人接手项目直接看标注了Mermaid代码的文档能同时理解代码逻辑和流程结构。第三个痛点是效率。画一张带判断分支的流程图用拖拽工具至少需要5到10分钟用Mermaid写文本熟练之后1分钟能完成第一版后面调整只改箭头和目标节点就行不会破坏整体布局。后面我会具体演示这个流程。2. 5分钟搭好VSCode实时预览环境插件安装与第一次出图2.1 插件选型Markdown Preview Enhanced和专用的Mermaid Support怎么选VSCode插件市场里搜Mermaid会出现很多结果我个人的建议是不要贪多装两个就够了一个是Markdown Preview Enhanced另一个是Markdown Preview Mermaid Support。Markdown Preview Enhanced以下简称MPE是老牌Markdown增强插件支持Mermaid渲染、导出PDF/HTML/PNG、自定义预览主题等功能非常全。Markdown Preview Mermaid Support则是一个专门负责Mermaid渲染的插件更轻量适合你只是想在普通Markdown预览里顺便看到流程图。如果你只是为了画Mermaid图不想折腾其他功能单独装Markdown Preview Mermaid Support也够用预览时按CtrlShiftV就能看到渲染效果。如果你和我一样平时还要写技术文档、导出汇报材料那建议以MPE为主它能做的事情更多。两个插件同时装一般不会冲突但我自己实际测试下来MPE一个就能覆盖绝大多数场景所以我日常主力就是MPE。2.2 一步步安装插件并完成基础设置第1步打开VSCode点击左侧边栏的扩展图标或者按快捷键CtrlShiftX进入扩展市场。在搜索框输入“Markdown Preview Enhanced”找到之后点Install等待安装完成。第2步如果你决定也装Markdown Preview Mermaid Support在搜索框换成这个名字同样点Install。装完之后建议你用CtrlShiftP打开命令面板输入“Reload Window”执行重新加载确保插件完全生效。这一步经常被忽略新装的插件有时不会立即生效尤其是在改了配置之后。第3步按Ctrl,打开设置页在搜索框里输入“markdown-preview-enhanced”确认插件配置能正常读取。MPE默认配置可以直接使用不需要额外改太多东西。我自己的设置里只改了两项一个是预览主题一个是代码块主题让暗色环境看起来更舒服{ markdown-preview-enhanced.previewTheme: one-dark.css, markdown-preview-enhanced.codeBlockTheme: one-dark.css }如果你用浅色主题这两项可以删掉保持默认值即可。配置不用贪多等熟悉以后按需再调整。2.3 新建文档写第一段Mermaid代码安装完成后新建一个文件命名为test.md。这里要注意文件后缀必须要是.md才行VSCode和插件才会按Markdown语法处理。在文件里粘贴下面的内容这一段是Mermaid源码不是普通文字graph TD A[开始] -- B{是否登录} B -- 是 -- C[进入首页] B -- 否 -- D[跳转登录页] D -- E[输入账号密码] E -- F{校验是否通过} F -- 通过 -- C F -- 不通过 -- E在Markdown里面真正要让插件识别成Mermaid代码块需要用三个反引号把这段源码包起来并在起始反引号后面写上语言标记mermaid。也就是说代码块的开头要写三个反引号加mermaid结尾写三个反引号。上面这段只是展示核心语法实际放进md文件时要加上包裹标记。写完之后按CtrlShiftV如果用的MPE也可以按CtrlK V把预览窗口放到右侧。只要配置正确右侧就会渲染出一张带判断分支的流程图开始节点是A菱形判断是BB分发到“是/否”两条支线登录校验不通过还会回到输入账号密码的节点重新循环。看到这张图说明你的实时预览环境已经通了。2.4 把预览体验调顺手常用快捷键与导出预览常用快捷键就两个CtrlShiftV是整页预览适合查看文档整体效果CtrlK V是侧边预览适合边改代码边看结果我平时用后者更多。MPE还有一个非常好用的功能是在预览窗口右键导出。你可以导出为PDF、PNG、JPEG、HTML等多种格式。我一般写方案文档时用HTML导出做PPT素材时用PNG导出。第一次导出PDF时插件可能会下载一个无头浏览器组件需要稍等一会儿如果下载失败就重新点一次一般重试就能成功。另外MPE支持在Markdown文件顶部写YAML front-matter来控制导出样式比如设置导出后的页面标题、纸张大小等。新手可以先不用管这个后续有需求再查官方文档。3. 流程图核心语法速览看懂节点、连线和框的含义3.1 节点形状、连接线和方向一篇文章看懂Mermaid流程图语法并不复杂核心就两块定义节点和定义连线。节点写法是通过“节点ID 形状 展示文字”组成的形状不同渲染出来的图形也不同。我用一个代码块把常用节点形状都串起来方便你对照graph LR A[矩形] -- B(圆角矩形) B -- C{菱形判断} C --|是| D((圆形)) C --|否| E[[子程序]] E -. 虚线注释 .- F[平行四边形] F G[加粗箭头]在这个例子里[ ]显示为矩形通常表示处理过程( )显示为圆角矩形常用来表示开始或结束{ }显示为菱形专门用来做判断分支( ( ) )显示为圆形一般代表连接点或特殊状态[[ ]]显示为子程序。连线的写法也有讲究--是普通实线箭头---是不带箭头的实线-.-是虚线箭头是加粗箭头--|文字|是给连线加上注释文字。方向声明位于graph关键字后面TD表示从上到下LR表示从左到右BT表示从下到上RL表示从右到左。我个人写逻辑流程时偏爱TD写模块关系图时用LR多一点。3.2 带判断和回环的登录流程一个例子覆盖80%场景日常画得最多的流程基本逃不出“开始 - 判断 - 分支处理 - 可能回环 - 结束”这套结构。我用登录场景再给你拆解一遍graph TD S([开始]) -- Input[输入账号密码] Input -- Check{账号密码正确?} Check -- 否 -- Input Check -- 是 -- Role{角色判断} Role -- 普通用户 -- Home[用户首页] Role -- 管理员 -- Admin[管理后台] Home -- E([结束]) Admin -- E这段代码里出现了几个关键手法一是用S([开始])把开始节点定义为圆形视觉上更贴近标准流程图二是判断节点Check的“否”分支又指回Input实现回环用户输错密码可以重新输入三是用Role{角色判断}做了二级判断体现不同角色的不同流向。这个结构可以直接套用到订单状态判断、权限校验、数据清洗流程等场景把节点文字换一下就是新图。3.3 不只是流程图时序图和简单的甘特图怎么写时序图在技术文档里出现的频率相当高尤其是描述接口调用关系时。比如下单支付Mermaid语法可以这样写sequenceDiagram participant U as 用户 participant O as 订单系统 participant P as 支付系统 U-O: 提交订单 O-P: 发起支付请求 P--O: 返回支付结果 O--U: 展示订单状态participant用来定义参与者并设置别名-表示实线请求--表示虚线返回。渲染出来的图会按时间顺序从上到下排列非常适合放在接口设计文档里比截图更清晰也更容易维护。甘特图我一般在排项目计划时用虽然功能没有专业项目管理软件强但胜在不需要离开文档环境gantt title 项目简单计划 dateFormat YYYY-MM-DD section 准备阶段 需求调研 :done, a1, 2025-03-01, 7d 方案设计 :active, a2, after a1, 5d section 开发阶段 模块开发 :a3, after a2, 10d每一行的格式大致是“任务名 冒号 状态标记 任务ID 时间范围”。done表示已完成active表示进行中未加状态标记的默认是待办。这个对写月度汇报、项目周报很好用。3.4 流程图各种框的含义其实和Mermaid是一一对应的结合前面说到的节点形状我再把标准流程图里常见框的含义和Mermaid写法对应起来。如果你是在大学作业或毕业设计里画系统流程图这些对应关系可以帮你把文本代码转换成符合课程要求的图。标准流程图元素含义Mermaid写法圆角矩形开始/结束A(开始)矩形处理过程A[处理]平行四边形输入/输出A[/输入/]菱形判断A{条件}圆形连接点A((连接点))箭头流程方向A -- B另外在Mermaid中还能用subgraph把一组节点包成子图渲染出来就是带边框的分组区域。这个特性在画模块边界、系统边界时非常有用比如把“用户端操作”和“服务端处理”分别放在两个子图里结构一眼就能看懂。子图写法是subgraph 标题开始end结束中间正常写节点和连线。4. 常见报错与问题排查实录白屏、语法错误、中文乱码一次说清4.1 预览白屏先按这三步排查预览白屏是我遇到最多的问题通常不是插件坏了而是没有满足触发条件。第一次看到白屏别慌按顺序排查先确认你打开的文件扩展名是.md如果后缀是.txt插件默认不会启动Markdown渲染再确认你使用的是MPE的预览而不是VSCode内置的普通Markdown预览两者的渲染范围不一样最后检查代码块是否被正确包裹了三个反引号语言标记是否写成了mermaid。如果这些都检查过仍然白屏可以执行一次CtrlShiftP输入“Reload Window”重新加载窗口。很多时候修改插件配置后窗口不重载新的设置不会立刻生效。我碰到过几次白屏最后都是重载窗口解决的。4.2 语法报错排查为什么网上复制的代码也报错Mermaid的报错信息一般会提示Parse error on line X但它不会直接告诉你是哪个符号写错了。我总结下来最常见的错误源有三个一是节点文字里混进了中文引号、中文括号或全角冒号Mermaid只能识别英文符号二是节点ID和显示文字之间的括号没配对比如写了A[文字忘了右括号三是子图或代码块的缩进不统一有的缩进用Tab有的用空格导致解析器认为节点定义发生了断层。网上复制的代买报错十有八九是上面第二种和第三种情况。我的处理方法是先把代码粘贴到Mermaid官方在线编辑器里它会用更友好的方式提示出错位置。确认语法没问题了再把代码搬回VSCode。还有一个小细节graph TD和graph TD;差一个分号有些版本对分号处理宽松但为了保险建议在方向声明后不要乱加分号。4.3 导出PDF/PNG中文变豆腐块字体和Puppeteer的问题MPE导出依赖Puppeteer调用无头浏览器渲染页面而在某些系统环境里默认字体列表里没有中文字体于是导出的PDF或PNG里中文全部显示成一个个方框。这个问题不是你的Mermaid代码写错了而是渲染环境缺少字体。解决办法有两种。简单粗暴的做法是给系统安装中文字体Windows一般自带微软雅黑macOS自带苹方一般不会缺Linux服务器或者精简系统最容易遇到这个问题装一个fonts-noto-cjk之类的字体包就能缓解。如果想要更可控可以给MPE配置puppeteer参数在settings.json里指定渲染时的默认字体或者导出时在HTML模板中设置font-family。我自己用的方式是尽量在流程节点里少放长句中文保留关键动作短语字体压力小了导出效果也更稳定。4.4 快捷键冲突、版本不一致、同事看不到图另一个高频问题是快捷键不管用。CtrlK V在某些键盘布局或插件组合下可能被其他插件抢走。这时可以按CtrlShiftP打开键盘快捷方式设置搜索“markdown.preview.open”这一类命令名改成自己习惯的按键。还有同事打开你的md文件看不到流程图常见原因是对方根本没装相应插件或者装的是老版本不支持你用到的新语法。Mermaid版本迭代比较快新版语法比如mindmap、stateDiagram-v2在旧插件上会直接报错或忽略。遇到这种情况我一般让同事升级插件到最新版或者干脆把导出的图片也提交到仓库里方便不装插件的人直接看图。4.5 一份可以直接抄的报错速查表为了方便你以后排查我把常见现象和解决办法整理成一张表现象可能原因解决办法预览白屏插件未生效 / 文件不是md / 代码块语言标记错误重新加载窗口确认文件后缀检查三个反引号包裹Parse error中文符号 / 括号不配对 / 缩进不一致替换成英文符号核对括号统一用空格缩进导出中文变方框渲染环境缺少中文字体安装系统字体或在Puppeteer配置里指定字体CtrlK V没反应快捷键冲突打开键盘快捷方式设置修改到新组合键同事打开看不到图插件未安装或版本过旧安装最新插件或同时提交导出图片预览不自动更新文件未保存 / 插件卡住CtrlS保存必要时Reload Window网络下载组件失败Puppeteer下载中断重试导出或更换网络环境后再试这张表我贴在项目文档里团队有人问起来直接发链接省了很多重复沟通时间。4.6 用熟之后我建议你收藏这几个独家技巧第一个技巧是建立自己的Mermaid模板库。我把登录判断、接口调用、项目排期这些高频场景的Mermaid代码存成一个mermaid-templates.md文件放在项目docs目录下。接到新需求时复制一段改一改5分钟出图真不是夸张。第二个技巧是善用%%注释。Mermaid支持在代码里写注释以两个百分号开头整行都会被忽略。我通常在比较复杂的分支前写一行注释说明这段流程的业务意图方便自己后续维护也让同事能快速理解。第三个技巧是节点文字尽量简短。如果你把一整个长句塞进节点渲染出来的框会变得特别宽整个图的比例很难看。我一般会把节点文字控制在6到8个汉字以内更长的说明写到连线文字或文档正文里。第四个技巧是养成保存预览的习惯。MPE默认会跟随文件变更自动刷新但在文件较多、图表较大的时候偶尔会延迟保存一下基本都能触发刷新。这不算什么高深操作但在关键时刻能避免“改了不生效”的错觉。我个人在实际使用中最大的感受是Mermaid并不是要取代所有画图工具它更适合那些需要频繁修改、需要进入版本库、需要多人协作的流程图形。你如果平时只是画一张不再改动的手绘风格示意图拖拽工具也没问题但只要图会变、会跟着代码走文本化的Mermaid就会让你轻松很多。最后再分享一个小技巧如果你要把Mermaid代码贴进博客、公众号或者团队知识库最好在发表前导出一次图片把图和代码同时放上去这样不管对方环境是否装插件都能快速看懂你要表达的结构。流程图画得再漂亮最终目的是让别人理解你的思路而不是炫技。
