必须安装Markdown Preview Mermaid Support插件并启用原生预览引擎，该插件唯一能将Mermaid渲染能力注入VS Code默认Markdown预览（Ctrl+K V），其他高亮或独立预览类插件无法替代；同时需确认文件为.md后缀、代码块标记为`mermaid、设置中markdown.preview.mermaid.enabled为true。
Mermaid 图表在 VSCode 里不渲染，90% 是插件没装对或预览引擎没切过去，不是语法问题。
必须装 Markdown Preview Mermaid Support，别被名字带偏
VSCode 原生 Markdown 预览（Ctrl+K V）默认不支持 Mermaid。很多用户误装了 Mermaid Preview 或 mermaid-markdown-syntax-highlighting，结果代码高亮有了，预览还是空白——因为这两个插件只负责语法提示或独立文件预览，不接管 Markdown 预览流程。
-
Markdown Preview Mermaid Support是唯一能“注入”Mermaid 渲染能力到原生预览的插件，安装后无需额外命令，只要预览打开就能生效 - 如果同时装了
Markdown Preview Enhanced，它会接管预览逻辑，此时要进设置确认markdown-preview-enhanced.mermaidEnabled为true，否则照样不渲染 - 插件名容易混淆，比如
Mermaid Syntax Highlight或Mermaid Live Editor都不能替代它
Ctrl+K V 不出图？先检查预览引擎和文件关联
即使插件装对了，VSCode 仍可能用错预览后端。常见现象是：点击“Open Preview”弹出空白页，或右键菜单里只有“Open Preview to the Side”，没有“Open Preview in Webview”选项。
- 打开命令面板（
Ctrl+Shift+P），输入Markdown: Select Markdown Previewer，选Default Markdown Preview（即原生预览） - 确保当前文件是
.md后缀，且 Mermaid 代码块标记为```mermaid，不是```mmd或```graph - 如果用的是
.mmd独立图表文件，需在.vscode/settings.json中加配置："files.associations": { "*.mmd": "mermaid" }，否则编辑器根本不识别语法
渲染失败但没报错？重点查这三处配置
Mermaid 渲染失败时 VSCode 往往静默失败，连控制台都不报错，排查要直奔配置项。
- 检查
settings.json中是否误启了markdown.preview.enableScripts：该选项默认关闭，若手动开启又未启用本地服务，会导致 Mermaid 脚本被拦截 - 确认
markdown.preview.mermaid.enabled是true（这是 VSCode 1.85+ 内置的 Mermaid 开关，旧版无此字段） - 如果用了深色主题但图表文字看不清，不是插件问题，而是 Mermaid 主题未适配：加配置
"mermaid.theme": "dark"或"default"，避免依赖插件默认值
甘特图/时序图显示异常？注意 dateFormat 和 participant 拼写
语法本身没问题，但 Mermaid 对关键字大小写和空格极其敏感，尤其跨图表类型时。
- 甘特图必须声明
dateFormat，如dateFormat YYYY-MM-DD，漏写或格式不匹配（如写成YYYY/MM/DD）会导致整张图空白 - 时序图中
participant后不能跟中文或特殊字符，participant 用户服务会失败，得写成participant UserService或加引号：participant "用户服务" - 流程图节点 ID 不能含空格或点号，
start node或api.gateway会中断渲染，改用下划线：start_node、api_gateway
真正卡住人的从来不是 Mermaid 语法多难，而是 VSCode 把“谁来渲染”“用哪套配置”“在哪种文件里生效”这三层逻辑拆得太散——插件、预览引擎、语言关联、全局设置，任意一环断开，图表就消失，且毫无提示。
