mermaid preview 插件需满足 vs code ≥1.77.0、文件正确识别为 mermaid 语言模式（如 .mmd 后缀或手动设置）、主题与缩放配置匹配（如 redux-dark/redux 及 max_zoom:5），并禁用冲突插件，否则将出现预览空白、不更新或主题错乱。
直接装 Mermaid Preview 插件就能渲染，但默认配置下常出现“预览空白”“不自动更新”“主题错乱”三类问题——核心不是装没装，而是 VS Code 版本、文件类型识别、主题配置这三点是否对齐。
确认 VS Code 版本 ≥ 1.77.0 且插件已启用
低于这个版本，Mermaid Preview 会静默失效，连错误提示都不给。不是卡顿，是根本没启动。
- 打开菜单栏「帮助 > 关于」，核对版本号；若低于
1.77.0，必须升级到最新版（2026 年 5 月最新稳定版为1.89.x） - 扩展面板（
Ctrl+Shift+X）搜索Mermaid Preview，确认状态为「已启用」而非「已禁用」或「已安装未启用」 - 安装或启用后，务必重启 VS Code —— 这步跳过，90% 的“预览不显示”问题就出在这儿
确保文件被识别为 Mermaid 语言模式
插件只对 .mmd、.mermaid 文件或 Markdown 中的 ```mermaid 代码块生效。如果用 .md 或 .txt 后缀写 Mermaid 代码，它只会当普通文本处理。
- 新建文件时，优先保存为
diagram.mmd（不是.md），这样 VS Code 会自动切换语言模式为mermaid - 若已在
.md文件中写```mermaid块，需手动触发语言模式：按Ctrl+K M→ 输入mermaid→ 回车，否则语法高亮和预览都可能不触发 - 想让所有
.mmd文件永久关联正确语言模式，加这条配置到settings.json："files.associations": { "*.mmd": "mermaid", "*.mermaid": "mermaid" }
修复预览主题错位与缩放异常
图表颜色发灰、文字糊成一团、放大后边缘裁切——大概率是主题配置没匹配当前 VS Code 主题，或者最大缩放值被锁死。
- 深色主题用户建议设
"mermaid.vscode.dark_theme": "redux-dark"，浅色主题用"mermaid.vscode.light_theme": "redux"（别用默认的default，兼容性差） - 大型甘特图或类图容易超出视口，需放开缩放上限：
"mermaid.vscode.max_Zoom": 5
- 如果预览窗口右上角没有缩放控件，检查是否误启用了
mermaid.preview.autoZoom（设为false可恢复手动缩放）
最易忽略的一点：多个 Mermaid 相关插件共存时（比如同时装了 Markdown Preview Mermaid Support 和 Mermaid Preview），它们会抢夺同一段代码的渲染权，导致预览闪退或样式冲突。只留一个主插件，其他相关插件建议禁用。
