mermaid preview插件不支持实时渲染，仅在保存后调用系统mmdc命令生成svg/png并嵌入html，需手动配置mmdc路径、严格遵循`mermaid语法规范，且内置预览受限于sublime沙箱，导出html更可靠。
Mermaid Preview插件根本不会“实时渲染”
Sublime Text 的 Mermaid Preview 插件不提供真正意义上的实时预览，它只是在你手动触发或保存后，调用系统级 mmdc 命令生成 SVG/PNG，再嵌入 HTML 页面——整个过程无 JS 执行、无浏览器沙箱内渲染、无 WebSocket 或轮询机制。所谓“实时”，实际是“保存 → 调 mmdc → 生成临时 HTML → 浏览器加载”，中间任何一环断掉，就卡在纯文本。
常见静默失败现象：
-
Cannot find mmdc：插件报错但没弹窗，只在 Sublime 控制台（Ctrl+`）里输出；不是插件坏了，是mmdc没装或路径填错 - ```mermaid 块显示为普通代码块：状态栏显示
Plain Text或文件后缀是.txt，插件直接跳过识别 - 图表区域空白 + 控制台无报错：说明
mmdc被调用了，但 Mermaid 语法有误（如用了flowchart TD而插件只认旧版graph TD）
必须手动配 mmdc 路径，且不能只写命令名
Mermaid Preview 不自带渲染器，也不走 Node.js require() 加载，它只执行 shell 命令。所以 mmdc --version 在终端能跑 ≠ Sublime 能找到它。
配置路径时注意：
- macOS 上
mmdc通常在/usr/local/bin/mmdc，但若用npm install -g mermaid-cli安装在用户目录，路径可能是/Users/xxx/.npm-global/bin/mmdc - Windows 上
mmdc.cmd默认在C:\Users\{user}\AppData\Roaming\npm\mmdc.cmd，必须带.cmd后缀，只写mmdc会失败 - 路径要填进
Preferences → Package Settings → Mermaid Preview → Settings – User，格式是："mmdc_path": "/usr/local/bin/mmdc"（字符串，不是数组） - 别用
~或环境变量，Sublime 不展开它们
```mermaid 块必须严格满足三要素
插件对代码块标识零容忍，差一个字符就当普通文本处理，且不报错。
合规写法仅一种：
将 Markdown 格式的回复转换为适合 Telegram 的富文本，避免渲染错误。适用于用户偏好 Markdown 但目标平台为 Telegram 的场景。
- 开头必须是
```mermaid（全小写，无空格，无后缀，无注释） - 内容必须用英文半角标点，禁止中文顿号、全角冒号、多余缩进或空行
- 结尾必须是独立一行的
```，前后不能有空格
错误示例：
```mermaid-js graph TD A[前端] --> B[API] ```
正确示例：
```mermaid graph TD A[Frontend] --> B[API] ```
注意：graph TD 兼容性比 flowchart TD 更好，尤其在旧版插件中；Mermaid v10+ 语法需确认插件版本是否支持（2026 年主流插件仍倾向 v9.x 解析器）
导出 HTML 比插件预览窗口可靠得多
Mermaid Preview 的内置预览窗口基于 Sublime 的 HTML 渲染沙箱，会拦截内联样式、拒绝加载外部字体、禁用 SVG <use></use> 引用——导致图标缺失、文字模糊、连线错位。而导出的 HTML 文件由浏览器原生加载，无此限制。
操作建议：
- 右键 →
Mermaid Preview: Export as HTML，生成.html文件 - 用 Chrome / Edge / Firefox 打开，不要用 Safari（对本地 file:// 协议限制更严）
- 如果图仍不显示，打开开发者工具（
F12），看 Console 是否有ReferenceError: mermaid is not defined—— 这说明你误用了依赖 JS 的方案（比如硬塞mermaid.min.js），而 Mermaid Preview 本就不走这条路
最易被忽略的一点：插件预览窗口里的“刷新”按钮毫无作用，它不重新调 mmdc，只重载已缓存的 SVG。真要重绘，必须改代码块内容并保存，或手动删掉 Cache/ 目录下的临时 SVG 文件。
