怎么在VSCode里绘制流程图-Mermaid插件语法与预览指南

怎么在VSCode里绘制流程图-Mermaid插件语法与预览指南

想在VSCode里优雅地画个流程图，结果代码写好了，预览却一片空白？别急着怀疑人生，问题往往出在几个不起眼的细节上。今天，咱们就来把Mermaid在VSCode里的正确打开方式彻底捋清楚。

Mermaid 代码块必须写成 ```mermaid，不是 ```flowchart 或 ```graph

这是第一道，也是最关键的一道坎。VSCode的插件识别Mermaid代码块，全靠那个固定的语言标识符。只有规规矩矩地写上```mermaid，后续的解析引擎才会被正确触发。如果你写成了```flowchart TD或者```graph LR，甚至只是漏掉了mermaid这个词，预览窗口大概率会把它当成一段普通的、没有高亮的代码文本处理——底部状态栏通常连个错误提示都懒得给，直接静默跳过。

下面这几个是典型的“错误示范”：

• ```flowchart LR → 插件不认识，直接按普通代码块显示。
• ```mermaid flowchart LR → 开头对了，但后面多写了“flowchart”这个关键词，反而会干扰解析器，可能报出类似 Parse error: Unexpected token 'flowchart' 的错误。
• ```mermaid-js 或 ```mmd → 这些都不是标准写法，自然得不到语法支持。

记住，唯一正确的写法是：以 ```mermaid 独占一行开头，换行后直接书写图表定义代码，最后再用 ``` 闭合。就这么简单。

预览不刷新？先确认文件已保存 + 检查 markdown.preview.autoRefresh 设置

代码写对了，图却没变？这可能是第二个“坑”。VSCode内置的Markdown预览器，默认行为是“保存后刷新”，而不是像Typora那样实时编辑、实时渲染。如果你修改了Mermaid代码后，没有习惯性地按一下Ctrl+S（或Cmd+S）保存文件，那么预览窗口里的内容就会永远停留在上一版本。这个特性常常被误认为是“插件坏了”。

遇到预览不动的情况，可以按这个顺序排查：

• 先保存文件：这是最直接的一步。
• 分清预览窗口：用快捷键 Ctrl+K V（Windows/Linux）或 Cmd+K V（Mac）会打开一个新的预览窗口，旧的窗口不会自动更新。要刷新当前已打开的预览，需要点击预览窗口右上角的刷新图标，或者聚焦预览窗口后按 Ctrl+R。
• 检查设置：在VSCode设置里搜索 markdown.preview.autoRefresh，确保它被勾选。如果你安装了 Markdown All in One 这类增强插件，则可能需要同时关注 markdown.extension.preview.autoUpdate 这个设置项。
• 远程开发场景：如果你在使用Codespaces、SSH远程开发等环境，文件系统事件监听可能不那么灵敏，自动刷新会失效。这时，最可靠的方法是手动执行命令面板（Ctrl+Shift+P）里的 Markdown: Refresh Preview 命令。

流程图方向与节点命名：flowchart LR 和带空格的 [节点名] 是刚需

进入语法层面，首先要注意版本演进。Mermaid从v10版本开始，已经弃用了旧的 graph TD 等语法，官方推荐统一使用 flowchart 这个关键字。图表的方向参数（LR 从左到右、TD 从上到下、RL 从右到左）必须紧跟在 flowchart 后面，中间不能换行，也不能加冒号或等号。

另一个高频出错点是节点命名。当节点名称包含空格、括号、斜杠等特殊字符时，必须用方括号 [] 将整个名称包裹起来，否则解析器会因识别错误而失败。

• 正确示例：A[用户登录]、B[API /v1/users]
• 需要警惕的写法：
  • A[用户 登录]（虽然两个空格在方括号内通常能解析，但不推荐，容易引发格式上的歧义）。
  • A[前端页面] → 如果忘了写方括号，名称会被截断，后续代码全部报错。
  • A(带括号节点) → 圆括号在Mermaid里有特殊语法含义，必须改用 [带括号节点]。

对于连接线上的分支标签，要用竖线 | 包裹，例如：B -->|是| C。不能写成 B --> 是 C 或 B --> "是" C。

插件选哪个？只装 Markdown Preview Mermaid Support 就够，别堆砌

插件生态丰富有时也是种甜蜜的烦恼。经过大量实践验证，对于绝大多数只需要在Markdown文档中绘制流程图、时序图的用户来说，只安装 Markdown Preview Mermaid Support 这一个插件就足够了。

它的优势非常明显：轻量、稳定、与VSCode原生预览深度集成。它不会抢夺编辑器焦点，不会弹出独立窗口，不依赖额外的Node.js服务，修改代码后一保存，预览立刻同步更新，体验非常流畅。

相比之下，其他一些插件可能会带来不必要的麻烦：

• Mermaid Preview：会打开一个独立的预览窗口，方便缩放和导出图片，但它经常与VSCode的原生预览功能冲突，同时启用时容易出现图表被渲染两次或样式错乱的问题。
• Markdown Preview Enhanced：功能确实强大，但它基于本地Node.js进程，环境配置稍复杂，容易因markdown-it等依赖缺失而报错。而且它的Mermaid支持需要额外配置，并非开箱即用。
• Mermaid Chart（官方插件）：更适合需要云同步、AI生成图表等高级场景。对于单纯的文档写作来说，显得有些“杀鸡用牛刀”，可能会拖慢启动速度，增加内存占用。

所以，给你的建议是：如果你主要就是在 .md 文件里画图，不妨禁用其他所有Mermaid相关插件，只保留 Markdown Preview Mermaid Support。这个简单的操作，能帮你避开80%以上“图为什么不显示”的诡异问题。

说到底，在VSCode里用Mermaid画图，真正的难点往往不在于语法本身有多复杂，而在于是否写对了 ```mermaid 这个“咒语”、是否记得保存文件、以及是否让多个插件在后台“打架”。把这三点盯紧了，你的流程图就能稳稳当当地呈现在预览里。