流程图这种玩意儿过去要靠 Visio、ProcessOn 这类可视化工具画框图、拉箭头、调对齐改一版逻辑基本等于重画一遍。我自己折腾了几年之后固定下来的方案很朴素用 VSCode 写 Markdown在 Markdown 里用 Mermaid 语法描述流程再装一个 Markdown Preview Mermaid Support 插件按CtrlK V就能在编辑器右侧看到实时预览。整个过程不用切换窗口也不用拖拽5 分钟足够跑通。这篇就把插件安装、基础配置、Mermaid 语法、各种框的含义和常见报错一次讲清楚适合正在写技术文档、毕业设计、系统流程图或者想提高文档可维护性的人。1. 为什么用 VSCode 写 Mermaid 流程图1.1 Mermaid 到底是什么Mermaid 是一个基于 JavaScript 的“文本图表工具”。它和 Markdown 很像Markdown 用文本表示排版结构Mermaid 用文本表示图形结构。你用一行flowchart TD声明方向再用几行文字描述“谁连到谁”渲染引擎自动把节点摆好、把线条连好、把颜色配上。GitHub 的 Markdown 预览、很多博客平台和笔记工具都内置了 Mermaid 渲染说明它已经成了文本绘图的通用语言。我最早用 Mermaid 是为了维护项目里的接口文档。以前画架构图、流程图用的是 Visio画完之后是一张图片存在docs目录里。一旦接口流程变了要打开.vsdx文件重新拖拽导出图片覆盖。更麻烦的是图片没法用git diff看出改动别人改了之后除非肉眼对比否则根本不知道哪里变了。Mermaid 本质是把图画代码化让流程图的修改变成一个普通的文本改动。这样的好处是直接进代码仓库版本管理评审时git diff能精确到某一根连线这是传统画图工具做不到的。1.2 实时预览解决的是“改图效率”问题有人会说Draw.io 也有实时预览为什么非要折腾 VSCode我的体验是VSCode 加 Mermaid 的组合解决的不是“画图”这一个点而是把“写文档”和“画流程”合并成了同一个动作。你在写 README、接口文档、方案设计时停下来画图是很打断思路的。用 Mermaid 之后流程图就嵌在文档对应的位置哪里需要流程说明哪里就写一段 Mermaid 描述。按一下快捷键右侧马上刷新思路不会断。特别是以下三类朋友我强烈建议试试第一类写技术文档的开发流程和代码同仓库维护第二类做毕业设计的学生画系统流程图、算法流程图、用户管理模块流程图放论文用文本画图比反复框选对齐快很多第三类做产品需求梳理的人用流程图表达判断分支、异常分支改起来比 PPT 舒服。你不需要成为前端工程师也不需要懂 Canvas、SVG会写几行文本就行。2. 五分钟快速搭建 Mermaid 实时预览环境2.1 环境准备VSCode 安装、中文界面与插件市场如果你电脑上还没有 VSCode先去官网下载安装包。这一步网上教程很多我只提醒两点一是尽量到官方站点下载避免搜索引擎出来的第三方下载站捆绑其他东西二是安装完成后建议顺手做两件事设置中文界面安装常用扩展。设置中文的方法是在扩展面板搜索“Chinese (Simplified) (简体中文) Language Pack”安装后右下角会提示重启重启后就是中文界面。很多人第一次打开 VSCode 被英文界面劝退这步能省掉很多认知成本。如果你之前已经折腾过 VSCode 配置 Python 或 C/C 环境那你对左侧扩展图标、命令面板、settings.json这些概念应该不陌生。没有配置过也没关系Mermaid 预览插件的安装比配置编译器简单得多不需要改系统变量不需要写launch.json只需要在扩展面板点一下 Install。插件市场就是 VSCode 左侧那个四个方块图标的扩展面板。搜索插件、安装、启用三步就能完成。需要提醒的是尽量只安装来自官方市场、开源地址明确、下载量高的插件。第三方搬运的插件市场可能存在安全风险还可能和官方插件冲突不建议碰。2.2 插件选型Markdown Preview Mermaid Support 与 Markdown Preview EnhancedMermaid 相关插件在扩展市场里非常多常见的有 Markdown Preview Mermaid Support、Markdown Preview Enhanced、Mermaid Editor、Mermaid Markdown Syntax Highlighting 等。我自己的建议是不追求全家桶先装一个稳定的预览插件。我主力用的是 Markdown Preview Mermaid Support作者是 Matt Bierner这个作者还做了 Markdown All in One 等一批高质量扩展。该插件可以直接在 VSCode 内置 Markdown 预览中渲染 Mermaid 图和CtrlShiftV、CtrlK V两个内置预览快捷键完美配合。如果你的需求不止流程图还想要导出 PDF、PNG、自定义 CSS、数学公式、图表等能力那就选 Markdown Preview Enhanced它内置了 Mermaid 支持功能更像一个完整的 Markdown 工作台。但注意这两个插件同时装也基本没问题前提是不要重复启用多个 Mermaid 插件。我见过有人在扩展面板里装了四五个同类插件结果预览时有的报错、有的空白、有的样式冲突最后把多余的禁用才恢复。所以装插件的原则很简单够用就行遇到问题再补别一开始就装一筐。安装步骤其实只有四步。第一步在扩展市场搜索“Markdown Preview Mermaid Support”第二步点击 Install第三步新建一个test.md文件第四步在文件里写一段最基础的 Mermaid 描述注意语言标识要填mermaid或mmd然后打开预览。如果你以前没有写过任何 Mermaid先别急着画复杂的从一个三行结构开始比如flowchart TD表示从上往下画然后写一个开始节点连到一个判断节点再连到结束节点。只要能渲染出来说明环境已经通了。这一步跑通之后后面所有问题都有了排查基础。2.3 打开预览的三种方式与快捷键设置VSCode 内置 Markdown 预览的快捷键有两个CtrlShiftV是在编辑器外单独打开一个预览页适合大屏对比CtrlK V是把预览窗口并排在右侧这是我最常用的。打开侧边预览后只要你在左边的 Markdown 文件里保存预览就会实时刷新。Mermaid 也是同一个刷新链路你改完节点文字切回预览页基本秒级更新。这个“实时”体验才是整个方案的核心价值。除了快捷键还可以用命令面板按CtrlShiftP输入“Markdown: Open Preview to the Side”回车。也可以直接右键编辑器标签页选择“打开侧边预览”。如果你觉得默认快捷键和别的插件冲突可以自定义按键。打开命令面板输入“Preferences: Open Keyboard Shortcuts”搜索命令markdown.showPreviewToSide然后修改绑定。下面是一个keybindings.json的示例把侧边预览绑定到CtrlAltV{ key: ctrlaltv, command: markdown.showPreviewToSide }保存后立即生效不用担心需要重启。我习惯把预览快捷键单独留在CtrlK V但如果你经常在终端和 VSCode 之间切换可以考虑改成更顺手的组合免得每次都要低头找按键。3. Mermaid 流程图核心语法与图形含义3.1 流程图骨架方向、节点和连线Mermaid 的 flowchart 语法其实不难核心就三件事方向、节点、连线。方向关键字放在图的最开始flowchart TD表示从上到下flowchart LR表示从左到右flowchart BT表示从下到上flowchart RL表示从右到左。画普通流程、系统流程图、算法流程图我一般用TD画时序相关的业务流转比如从用户点击到后台处理的调用链用LR更合适。节点写成节点ID[展示文本]的形式ID 是你给这个节点起的唯一名字展示文本是渲染后显示出来的内容。连线最基本的是--表示有向箭头---表示无箭头连线-.-表示虚线箭头表示粗箭头。还可以在连线上写字比如A --|是| B表示从 A 到 B 的连线标签是“是”。整个图就是由这些行组成的。你需要理解一个关键点Mermaid 渲染时会自动计算节点位置你不用告诉它“这个框放在哪里”只需告诉它“这个框和那个框什么关系”。这也是 Mermaid 比拖拽画图效率高的原因它把布局这个最耗时的活儿交给了渲染引擎。如果一开始不熟悉我建议先画一个“开始 - 判断 - 结束”的三节点图把方向、节点、连线这三个概念跑通。然后逐步增加节点文本、连线标签、不同形状。不要一上来就画几十个节点的大图那样报错时不好定位自动布局也会让你很崩溃。3.2 各种框的含义与适用场景用 Mermaid 画流程图最常被问到的是“这些框到底什么意思”。传统流程图里不同框形有约定俗成的含义。Mermaid 通过节点语法的不同括号来区分形状。我整理了一个常用速查表框形语法渲染效果含义与场景A[文本]矩形普通处理步骤、页面、动作A(文本)圆角矩形开始或结束或表示一般操作A([文本])体育场形开始/结束比圆角矩形更圆A[[文本]]子程序函数、模块、已封装流程A[(文本)]圆柱体数据库、存储常用于系统流程图A((文本))圆形连接点、汇合点A{文本}菱形判断、分支、条件A{{文本}}六边形准备、预处理动作A文本]非对称矩形输出、展示给用户的动作A[/文本/]平行四边形输入/输出画常规业务流程图时我一般只用三种形状矩形表示操作菱形表示判断圆角矩形或体育场形表示开始结束。用太多形状反而可读性差。如果是画图书馆管理系统毕业设计里的流程图也不建议把所有节点都画在同一张图里。可以把登录、借书、还书、管理员操作拆成几个子图或几张图每一张用上述基本形状即可。形状只是辅助读者理解不要为了体现语法多厉害而炫技。3.3 子图、样式和中文渲染处理当流程图内容超过十来个节点建议用subgraph划分子图。子图的基本结构是subgraph 子图名开头end结束子图里可以放若干节点和连线。它非常适合表达模块边界比如在一个用户管理模块流程图中登录、权限校验、用户 CRUD、日志记录分别放到不同的子图里整个图看着就清楚很多。渲染时子图外面会有边框和题目标签读者一眼可以分清楚这是哪个系统或哪个阶段。样式方面可以为单个节点写style 节点ID fill:#f66,stroke:#333,color:#fff也可以用classDef定义一组样式再用class 节点ID,节点ID2 类名批量应用。比如把判断节点统一涂成黄色把异常节点统一涂成红色对阅读体验提升很大。我的经验是样式规则不要超过三四种颜色否则图会显得很花。关于中文显示这是很多新手会踩的坑。Mermaid 本身支持中文文本但默认渲染字体不一定覆盖中文字符有时候会显示成方块或者因为字体宽度问题导致节点宽度异常。解决办法是在 Mermaid 初始化指令里指定字体在代码块开头加一段初始化配置把fontFamily设置成系统中文字体。不同的预览插件对初始化指令的支持不太一样如果写完没效果优先看插件的 README确认支持哪种初始化写法。另一个更省事的办法是换用 Markdown Preview Enhanced 的主题很多国内用户会在它的配置里设置中文字体。实测下来在 VSCode 里用中文字体时大部分节点都能正常显示。4. 从流程图扩展到思维导图、BPMN 与文档工作流4.1 用 Mermaid 快速画思维导图和用户模块流程图Mermaid 新版本还支持思维导图mindmap写法更简单类似列表缩进。不过 VSCode 里的 Markdown 预览插件不一定支持最新语法所以如果你只是要画思维导图我更推荐直接用 XMind 这类专业工具它内置了漂亮的主题和导出能力。Mermaid 的长处还是在需要版本管理的场景。比如用户管理模块流程图这个在系统设计文档里特别常见用户进入系统先判断是否已登录未登录跳到登录页登录后判断角色管理员可以进入管理后台普通用户只能进入个人中心所有操作记录写日志。这样一个流程用 Mermaid 文本描述放在文档中比截图更好维护。做毕业设计的时候很多人会为了“流程图怎么画”发愁。我的建议是先用 Mermaid 在 VSCode 里画好导出为 PNG/SVG再粘贴到论文里。好处是你在论文草稿阶段可以随时改不用反复截图。比如图书馆管理系统里的还书流程读者提交还书请求系统检查是否有逾期罚款如果有就提示先交罚款没有就登记归还、更新库存状态最后生成还书记录。用文本描述这样一个流程几分钟就能画好PDF 导出后分辨率也够用。4.2 BPMN 网关、泳道与 Mermaid 的对应关系如果是正规的企业流程建模你会遇到 BPMN 这个名词。BPMN 是一种比 Mermaid 严谨得多的流程建模标准里面有事件、活动、网关、泳道等概念。BPMN 网关的使用也比较讲究排他网关、并行网关、包容网关、事件网关各有不同的语义。Mermaid 的 flowchart 虽然可以画出类似的分支结构但没有严格的网关语义也没有泳道概念。所以你如果为了应付一个需要严谨建模的项目应该去用支持 BPMN 的专业工具而不是硬用 Mermaid。但这不代表 Mermaid 没用。在很多日常场景下Mermaid 的作用是“快速表达想法草稿”。你可以在 VSCode 里用 flowchart 把流程先画出来给团队确认逻辑等逻辑确认无误再根据规范迁移到 BPMN 工具。这样等于用 Mermaid 承担了“草图阶段”的工作。我个人很少在正式交付文档里把 Mermaid 直接交给客户但经常用它做内部沟通和方案讨论。4.3 联合 Typora、XMind、Zotero 等工具打通写作链路Mermaid 现在已经不是 VSCode 的专属能力。Typora 内置了对 Mermaid 的支持打开.md文件就能渲染适合快速写作XMind 负责复杂思维导图Zotero 是文献管理工具写论文时收集参考文献。我自己的文档工作流是这样VSCode 写 Markdown 正文Mermaid 画流程图和时序图Zotero 管理参考文献最后导出 Word 或 PDF 交给导师或同事。Mermaid 图作为文本文件存到项目目录里随时可以再编辑。如果你愿意折腾还可以在 VSCode 里装一些 AI 辅助插件比如 Codex 这类代码生成工具。用自然语言描述你想要的流程它有可能生成一份 Mermaid 代码你再粘贴到 Markdown 里微调。我实测下来简单的分支流程 AI 基本没问题复杂的业务规则还是自己写更可控。总之Mermaid 的价值是让流程图的“源文件”变成纯文本这意味着它可以和其他工具链无缝衔接不再是一张没法追溯的图片。5. 常见报错与排查实录5.1 预览空白、一直转圈或刷新无响应这是我在各个群里被问到最多的一个问题。预览打开后是一片空白或者一直显示加载中常见原因有三个。第一插件没有真正启用。装完插件后VSCode 有时候需要重载窗口才生效你直接在命令面板执行“Developer: Reload Window”即可。第二你打开的不是 Markdown 文件或者当前文件后缀不是.md。VSCode 的 Markdown 预览只对 Markdown 文件生效如果你建了一个.txt文件自然渲染不了。第三Markdown 里的 Mermaid 语言标识写错了。预览插件依靠语言标识判断哪段内容是 Mermaid识别不到就不会渲染。排查顺序我建议这样先确认扩展面板里已启用插件再确认文件后缀和预览方式然后新建一个最简单的测试文件只写几行 Mermaid 描述最后如果还不行把所有其他 Markdown 预览类插件全部禁用重载窗口再试。大多数情况下问题都出在插件冲突上而不是语法本身。如果你装了 Zotero 翻译插件之类的第三方工具它不会影响 VSCode但如果你装了多个 Markdown 预览扩展冲突概率会显著上升。5.2 语法看着没问题但渲染成乱码或样式错乱渲染出来但形状、颜色或文字不对这种情况一般是语法细节问题。比如节点文本里带了中文括号解析器容易被搞混节点 ID 用了空格也会报错。我遇到过一个很典型的错误想在节点文字里写“是否登录”直接把整句话写在方括号里看着没问题但 Mermaid 对某些字符敏感导致解析中断。解决办法是给文本加引号比如A[是否登录?]大部分情况下能解决。还有版本差异问题。旧版本的 Mermaid 只支持graph TD新版本推荐flowchart TD。如果你的插件版本比较旧写成flowchart可能不识别如果你在某个在线编辑器里写flowchart回到老插件报错那么改成graph试试。方向关键字拼写错误也很常见TD写成了DT报错提示一般会很明确直接看报错所在行就能定位。遇到样式错乱比如线太多交叉、节点互相重叠多数不是语法问题而是图画得太复杂。Mermaid 自动布局适合节点数量适中的图超过二十个节点就别硬放在一张图里用子图拆分是最好的解药。5.3 快捷键失效、预览窗口被侧边栏挡住CtrlK V在部分键盘布局或远程开发环境里确实可能不生效。如果你用的是远程 SSH、WSL 或容器开发某些键会被终端或另一个扩展截获。这时候不用换电脑直接改快捷键绑定。按CtrlShiftP输入“Preferences: Open Keyboard Shortcuts”搜索markdown.showPreviewToSide看当前绑定被谁占了把它改成你顺手的组合键比如前面提到的CtrlAltV。改完立刻能用这也是 VSCode 比普通 Markdown 编辑器灵活的地方。预览窗口打开后如果你觉得右侧预览被文件树或代码面板挡住可以把预览编辑器拖到独立的窗口或者在命令面板里选择“Markdown: Open Preview”而不是“Open Preview to the Side”。在 Markdown Preview Enhanced 的配置里也有一项可以控制预览窗口的打开方式通常叫autoOpenPreviewToTheSide。打开之后每次进入 Markdown 文件都会自动并排预览省得每次按快捷键。5.4 插件版本冲突、升级后崩溃有一类问题不是配置引起的而是插件版本或 VSCode 版本升级造成的。最常见的情况是某天 VSCode 自动更新某个 Markdown 扩展跟着更新然后 Mermaid 预览突然失效。遇到这种问题先别怀疑是自己配置错了。打开 OUTPUT 面板在右上角下拉框里选择对应扩展的日志看看有没有红色报错。如果是扩展版本和 VSCode 不兼容可以直接在扩展列表中点击插件选择“Install Another Version”回退到上一个稳定版本。另一个经验是不要同时启用多个功能重叠的 Markdown 预览插件。Markdown Preview Enhanced、Markdown Preview Mermaid Support、Markdown All in One 这几个扩展功能有重合一起使用时可能会存在样式冲突或重复渲染。我自己的习惯是只装一个 Markdown Preview Mermaid Support 加 Markdown All in One够用且稳定。如果某个项目需要 Markdown Preview Enhanced 的导出能力我会单独在工作区里启用而不是全局启用。5.5 报错信息速查表这一节把常见报错和解决办法整理成一张表方便遇到问题时快速定位。你可以把这张表打印出来贴在显示器旁边也可以存在项目文档里遇到问题直接按图索骥。现象常见原因处理建议预览空白插件未启用或重载未生效执行 Reload Window查看扩展状态Mermaid 代码原样显示语言标识错误或插件不支持检查代码块语言标识确认插件支持报错Syntax error in textMermaid 语法错误检查节点 ID、括号、引号、箭头写法中文显示方块字体不支持中文字符初始化指定fontFamily或更换预览主题CtrlK V没反应快捷键冲突打开 Keyboard Shortcuts 重新绑定图渲染但线交叉严重节点过多、自动布局过载拆分子图或拆成多张图更新后报错崩溃插件或 VSCode 版本不兼容查看 OUTPUT 日志回退插件版本上面这些解决方案是我在实际项目中反复验证过的。大部分问题不是单一原因而是多个因素叠加。遇到报错先别慌按表格里的顺序逐项排查一般都能解决。如果表格里的都试过还不行最后一个通用办法是把 VSCode 设置清空、扩展全部禁用再从零开始加回来往往能找到那个隐藏的元凶。6. 个人实操心得与最后提醒6.1 我踩过的坑和沉淀下来的习惯我用了 Mermaid 加 VSCode 至少三年踩过的坑比写出来的多。最开始我也装了一堆插件结果光是猜哪个插件在打架就花了一个晚上。现在我坚持一个原则预览插件只装一个语法拿不准先到 Mermaid Live Editor 里验证再粘回 VSCode。Mermaid Live Editor 是官方出的在线测试工具粘进去就能看渲染结果报错提示也比本地插件更直接。这个习惯帮我把排查时间压缩了很多。另外一个很重要的习惯是给文件命名。给团队或论文用的时候我会把 Mermaid 代码单独放在docs/flow目录下每个图一个.md文件命名带上模块名和日期。这样做的好处是以后流程变更时能通过 Git 历史看到每一版改动回滚也方便。如果只是临时画一个图给别人看那直接在 Markdown 文档里写就好不用单独拆分。我见过太多人在一个文档里堆了几十张 Mermaid 图最后改图时连自己都找不到对应代码在哪一段拆开管理会舒服很多。6.2 最后分享一个提速小技巧最后分享一个我每次教别人都会说的小技巧不要一上来就背语法你需要记住的就三样东西——方向、节点、连线。遇到拿不准的形状和样式随时打开 Mermaid 官方文档或者 Mermaid Live Editor现场验证。你可以把常用的模板存成一个代码片段比如“开始-判断-结束”的基础框架以后要画任何流程图复制模板改文字就行不用从零开始写。比如我要画一个登录流程脑子里只要想清楚开始节点用一个圆角矩形判断“是否已登录”用菱形已登录和未登录各走一条线最后进入对应页面或抛出错误。把这些关系用文本表达出来Mermaid 自动排版VSCode 实时预览。这个过程熟练之后真的不需要五分钟就能完成。等你看懂了自己画出来的图再回头看 Visio 里反复拖框拉线的日子大概率会觉得以前的效率实在浪费了太多时间。