必须安装官方 mermaid preview 插件（作者 bierner），用 mermaid 代码块包裹语法，通过全局配置 mermaid: config 统一样式，禁用 live preview 提升稳定性。
Mermaid 插件没生效？先确认安装的是官方插件
VSCode 里 Mermaid 渲染不是开箱即用的，必须装对插件。很多人搜“Mermaid 插件”点进一个名字带 mermaid 但作者是个人的插件，结果预览空白或报错 mermaid is not defined。
- 只装
Mermaid Preview（作者：bierner）——这是目前最稳定、VSCode 官方市场推荐的插件，支持实时预览和导出 - 别装
Markdown Preview Mermaid Support（已弃用）、Mermaid Markdown Syntax Highlighting（只高亮不渲染）这类功能残缺的插件 - 装完后重启 VSCode，打开任意
.md文件，右键选择Open Preview to the Side，不是靠文件名后缀或设置自动触发
流程图语法写对了，但预览还是空？检查容器格式和缩进
Mermaid 在 Markdown 中必须用特定代码块包裹，且语言标识必须是 mermaid，大小写敏感；任何多余空格、缩进或换行都可能让解析器静默失败。
- 正确写法：
```mermaid flowchart LR A --> B ``` - 错误常见点：
```Mermaid（首字母大写）、```mermaid-js、```mermaid ```（末尾多空格）、代码块前后有空行但缩进不一致 - 不支持在行内用
$包裹（如$flowchart LR$），Mermaid 不是 LaTeX，只认完整代码块 - 如果用了中文节点名，确保 VSCode 编码为 UTF-8（默认就是），否则可能显示方块或乱码
预览卡顿、图表错位或导出 PNG 失败？关掉「实时渲染」和「动画」
Mermaid 默认启用动画过渡和复杂布局计算，对稍大的流程图（节点 >30 个）或低配机器，会导致预览延迟、滚动卡顿，甚至导出时崩溃为黑图。
- 在 VSCode 设置中搜索
mermaid，把Mermaid: Live Preview设为false—— 改成手动刷新更稳 - 在代码块上方加注释关闭动画：
```mermaid %%{init: {'theme': 'default', 'flowchart': {'useMaxWidth': false, 'htmlLabels': true}}}% flowchart LR A --> B ``` - 导出 PNG 失败常见于含 SVG 滤镜或 CSS 自定义样式的图，简化样式或改用
export as SVG再转 PNG 更可靠
想复用样式或统一主题？直接改 VSCode 全局配置，别硬塞 inline config
每次都在每个代码块顶上写一长串 %%{init: {...}}% 很容易漏括号、引号不匹配，而且无法跨文件复用。Mermaid Preview 支持全局配置，这才是正解。
- 打开 VSCode 设置（
Ctrl+,），搜索mermaid config，编辑Mermaid: Config字段 - 填入 JSON 格式配置，例如：
{ "theme": "forest", "flowchart": { "useMaxWidth": false, "htmlLabels": true } } - 改完不用重启，新打开的预览窗口立即生效；旧窗口需手动刷新（
Ctrl+R或右键 →Reload Preview） - 注意：这个配置只影响 Mermaid Preview 插件，不影响其他工具（如 Typora 或 GitHub），别指望它让 GitHub 也渲染成功
Mermaid 的坑不在语法本身，而在 VSCode 插件链路太长：插件选错 → 渲染器不加载 → 语法写对也白搭；配置放错位置 → 每次都要手调 → 最后干脆放弃。真正省事的做法，是把插件、代码块格式、全局配置这三步钉死，后面就只是写图的事了。
