必须安装bierner.markdown-mermaid插件，仅此官方认证插件支持VS Code中Mermaid图表实时预览与导出；代码块严格写作`mermaid且前后空行无缩进；文件需保存并手动触发预览（Ctrl+Shift+V），禁用其他Markdown预览插件以防冲突。
必须装对插件：只认
VSCode 里 Mermaid 渲染不是开箱即用的，装错插件等于白忙。搜“Mermaid”时点进非官方插件（比如作者是个人、名字带
或
的），大概率预览空白或报错
。
唯一推荐安装的是：
（作者 bierner，VSCode 官方市场标“Verified”）。它支持实时预览、导出 PNG/SVG、全局配置，且持续维护。别装
（已弃用）或
（只高亮不渲染）。
装完必须重启 VSCode；否则即使代码写对，预览也无反应。
是唯一合法代码块标识
Mermaid 不识别
、
、
，也不接受末尾空格或大小写错误（如
）。
正确写法严格如下：
常见踩坑点：
VSCode 1.118
微软正式发布 Visual Studio Code 1.118 版本 。本次更新重点强化了 AI 开发体验与企业管理能力，其中最引人注目的是新增 Copilot CLI 远程控制功能，允许开发者通过手机或网页远程监控和接管 AI 会话 。同时，为了提高 AI 的运行性价比，新版本优化了令牌缓存策略以降低成本 。此外，1.118 版还引入了 Chronicle 本地历史追踪、TypeScript 7.0 支持以及更严格的企业级访问管控 。
下载
代码块前后有空行但缩进不一致 → 解析静默失败
用了中文节点名却没保存为 UTF-8 编码 → 显示方块（不过 VSCode 默认就是 UTF-8，一般不用调）
在行内用
→ Mermaid 不是 LaTeX，完全不认
预览不显示？先查这三件事
90% 的“图没出来”问题都卡在这三个地方：
文件没保存 —— VSCode 内置预览默认是「保存后刷新」，改完代码不按
，预览永远不动
没手动触发预览 —— 右键 .md 文件 →
Open Preview to the Side
（不是靠后缀自动开）；或者用快捷键
插件冲突 —— 禁用所有其他 Markdown 预览类插件（比如
），只留
测试
如果底部状态栏出现
，把鼠标悬停在代码块上，通常会提示具体哪行少括号、多冒号或方向参数写错（比如
中多了冒号）。
方向、节点、分支的写法不能松懈
Mermaid v10+ 已弃用
等旧语法，统一用
/
。方向参数必须紧跟
后，不能换行，也不能加等号或冒号。
节点命名规则很实在：
含空格、斜杠、括号的节点，必须用方括号包裹：
✅，
❌（圆括号是语法符号）
分支标签必须用竖线：
✅，
或
❌
箭头类型区分语义：
普通实线，
加粗强调，
虚线表示可选路径
复杂图容易卡顿或导出黑图，不是语法问题，而是动画和布局计算拖垮了性能。关掉
设置，改用手动刷新；导出优先选 SVG，再转 PNG 更稳。
bierner.markdown-mermaidmermaid-supportmermaid-syntaxmermaid is not definedbierner.markdown-mermaidMarkdown Preview Mermaid Supportmermaid-markdown-syntax-highlighting```mermaid```flowchart```graph```mermaid-js```Mermaid```mermaid
flowchart LR
A[开始] --> B{判断}
B -->|是| C[成功]
B -->|否| D[失败]
```$flowchart LR$Ctrl+SCtrl+Shift+Vmarkdown-preview-github-stylingbierner.markdown-mermaidMermaid: Parse errorflowchart: LRgraph TDflowchart LRflowchart TBflowchartA[API /v1/users]A(登录)B -->|是| CB --> 是 CB --> "是" C-->==>-.->Mermaid: Live Preview