mermaid代码块必须严格写作mermaid，不可用flowchart或`graph；需保存文件并启用markdown.preview.autorefresh，推荐仅安装markdown preview mermaid support插件。
Mermaid 代码块必须写成 ```mermaid，不是 ```flowchart 或 ```graph
VSCode 渲染 Mermaid 的前提是识别出语言标识符。只有 ```mermaid 这一固定写法才能被插件（如 Markdown Preview Mermaid Support）捕获并触发解析。写成 ```flowchart TD、```graph LR 或漏掉 mermaid 都会导致预览空白——底部状态栏甚至不会提示错误，只是静默跳过。
常见误写：
-
```flowchart LR→ 不识别，当普通代码块处理 -
```mermaid flowchart LR→ 多余空格+关键词干扰，部分插件会报Parse error: Unexpected token 'flowchart' -
```mermaid-js或```mmd→ 无对应语法支持，不渲染
正确写法唯一：以 ```mermaid 开头，换行后直接写图定义，结尾用 ``` 闭合。
预览不刷新？先确认文件已保存 + 检查 markdown.preview.autoRefresh 设置
VSCode 内置 Markdown 预览默认是「保存后刷新」，不是 Typora 那种编辑即变。改完 Mermaid 代码却不点 Ctrl+S，预览窗口永远不变——这是最常被当成“插件坏了”的原因。
检查项：
- 快捷键
Ctrl+K V（Windows/Linux）或Cmd+K V（Mac）打开的是新预览窗，旧窗口不会自动更新；要刷新当前预览，得点右上角刷新图标，或按Ctrl+R（聚焦预览窗后） - 设置中搜索
markdown.preview.autoRefresh，确保勾选；若用Markdown All in One插件，则要看markdown.extension.preview.autoUpdate - 远程开发（如 Codespaces、SSH）下文件系统事件可能失效，此时只能手动执行命令面板里的
Markdown: Refresh Preview
流程图方向与节点命名：flowchart LR 和带空格的 [节点名] 是刚需
Mermaid v10+ 已弃用 graph TD 等旧语法，推荐统一用 flowchart 关键字。方向参数（LR / TD / RL）必须紧跟其后，不能换行，也不能加冒号或等号。
节点名含空格、括号、斜杠等字符时，必须用方括号包裹，否则解析失败：
- ✅
A[用户登录]、B[API /v1/users] - ❌
A[用户 登录]（中间两个空格没问题，但不推荐）→ 实际可用，但易引发缩进歧义 - ❌
A[前端页面]→ 若未包裹，会被截断为A[前端，后续报错 - ❌
A(带括号节点)→ 圆括号是语法符号，必须用[带括号节点]
分支标签用竖线包裹：B -->|是| C，不能写成 B --> 是 C 或 B --> "是" C。
插件选哪个？只装 Markdown Preview Mermaid Support 就够，别堆砌
实测下来，Markdown Preview Mermaid Support 是目前最轻量、最稳定、与 VSCode 原生预览集成最深的方案。它不抢焦点、不弹独立窗口、不依赖 Node.js 服务，改完保存立刻生效。
其他插件的问题点：
-
Mermaid Preview：开独立窗口，缩放/导出方便，但会和原生预览冲突，同时启用时经常出现双渲染或样式错乱 -
Markdown Preview Enhanced：功能强，但基于本地 Node.js 进程，容易因markdown-it缺失报错；且它的 Mermaid 支持依赖额外配置，不如前者开箱即用 -
Mermaid Chart（官方）：适合云同步、AI 生成等高级场景，对纯文档写作属于过度设计，启动慢、内存占用高
如果你只在 .md 文件里画图，禁用所有其他 Mermaid 相关插件，只留 Markdown Preview Mermaid Support，能避开 80% 的“图不显示”问题。
真正卡住人的往往不是语法多难，而是 ```mermaid 少了个字母、文件没保存、或者三个插件在后台互相覆盖预览通道。把这三处盯死，流程图就能稳稳出来。
