必须安装bierner.markdown-mermaid插件，仅此官方认证插件支持vs code中mermaid图表实时预览与导出；代码块严格写作`mermaid且前后空行无缩进；文件需保存并手动触发预览（ctrl+shift+v），禁用其他markdown预览插件以防冲突。
必须装对插件：只认 bierner.markdown-mermaid
VSCode 里 Mermaid 渲染不是开箱即用的，装错插件等于白忙。搜“Mermaid”时点进非官方插件（比如作者是个人、名字带 mermaid-support 或 mermaid-syntax 的），大概率预览空白或报错 mermaid is not defined。
唯一推荐安装的是：bierner.markdown-mermaid（作者 bierner，VSCode 官方市场标“Verified”）。它支持实时预览、导出 PNG/SVG、全局配置，且持续维护。别装 Markdown Preview Mermaid Support（已弃用）或 mermaid-markdown-syntax-highlighting（只高亮不渲染）。
装完必须重启 VSCode；否则即使代码写对，预览也无反应。
```mermaid 是唯一合法代码块标识
Mermaid 不识别 ```flowchart、```graph、```mermaid-js，也不接受末尾空格或大小写错误（如 ```Mermaid）。
正确写法严格如下：
```mermaid
flowchart LR
A[开始] --> B{判断}
B -->|是| C[成功]
B -->|否| D[失败]
```
常见踩坑点：
文档转 Markdown 转换器 - 将 DOCX、PPTX、Excel 文件转换为 Markdown。用于从 Word 文档、PowerPoint 演示文稿或 E... 提取内容。
- 代码块前后有空行但缩进不一致 → 解析静默失败
- 用了中文节点名却没保存为 UTF-8 编码 → 显示方块（不过 VSCode 默认就是 UTF-8，一般不用调）
- 在行内用
$flowchart LR$→ Mermaid 不是 LaTeX，完全不认
预览不显示？先查这三件事
90% 的“图没出来”问题都卡在这三个地方：
- 文件没保存 —— VSCode 内置预览默认是「保存后刷新」，改完代码不按
Ctrl+S，预览永远不动 - 没手动触发预览 —— 右键 .md 文件 → Open Preview to the Side（不是靠后缀自动开）；或者用快捷键
Ctrl+Shift+V - 插件冲突 —— 禁用所有其他 Markdown 预览类插件（比如
markdown-preview-github-styling），只留bierner.markdown-mermaid测试
如果底部状态栏出现 Mermaid: Parse error，把鼠标悬停在代码块上，通常会提示具体哪行少括号、多冒号或方向参数写错（比如 flowchart: LR 中多了冒号）。
方向、节点、分支的写法不能松懈
Mermaid v10+ 已弃用 graph TD 等旧语法，统一用 flowchart LR / flowchart TB。方向参数必须紧跟 flowchart 后，不能换行，也不能加等号或冒号。
节点命名规则很实在：
- 含空格、斜杠、括号的节点，必须用方括号包裹：
A[API /v1/users]✅，A(登录)❌（圆括号是语法符号） - 分支标签必须用竖线：
B -->|是| C✅，B --> 是 C或B --> "是" C❌ - 箭头类型区分语义：
-->普通实线，==>加粗强调，-.->虚线表示可选路径
复杂图容易卡顿或导出黑图，不是语法问题，而是动画和布局计算拖垮了性能。关掉 Mermaid: Live Preview 设置，改用手动刷新；导出优先选 SVG，再转 PNG 更稳。
