Mermaid渲染卡顿、缩放失真、大图白屏的根本原因是默认全量重绘与图表规模不匹配，需改用增量更新、固定SVG容器尺寸、禁用自动尺寸计算、清理子图事件监听，并将解析移至Web Worker以解除主线程阻塞。
Mermaid 插件画布卡顿、缩放失真、大图加载白屏——根本不是配置问题，而是渲染策略没对齐实际图表规模。直接改 maxTextSize 或调高 maxHeight 只会让问题更隐蔽。
Mermaid 渲染卡在「完整重绘」阶段怎么办
Mermaid 默认每次内容变更都重建整个 SVG，哪怕只改了一个节点标签。这对 200+ 节点的流程图就是性能黑洞。
- 确认是否触发了全量重绘：打开开发者工具（
Developer: Toggle Developer Tools），在 Console 输入mermaid.startOnLoad = false，手动调用mermaid.render()测试单次耗时 - 启用增量更新：在插件设置中开启
incrementalRendering（部分 Mermaid 插件需 v1.10.0+），它会比对 AST 差异，仅替换变动 DOM 元素 - 避免在
onDidChangeTextDocument中无节制调用render()；改用防抖 + 内容哈希比对，例如if (hash(newText) !== hash(oldText)) { render() }
SVG 容器尺寸失控导致滚动/缩放卡顿
Mermaid 输出的 <svg> 默认宽高是 auto，浏览器反复重排布局，尤其嵌入 Webview 或 Markdown 预览时。
- 强制固定容器尺寸：在预览区域外层加
div并设width: 100%; height: 600px; overflow: auto;，再让<svg>通过viewBox自适应 - 禁用 Mermaid 的自动尺寸计算：在初始化时传入
{ theme: 'default', securityLevel: 'loose', startOnLoad: false, useMaxWidth: false } - 缩放卡顿多因
transform: scale()触发 CPU 渲染；改用 CSSzoom（仅 Chromium）或用scaleX/Y+will-change: transform提示 GPU 加速
大量子图嵌套引发内存泄漏
Mermaid 支持 subgraph，但每层嵌套都会生成独立 <g> 组并绑定事件监听器。未清理时，关闭预览页后 DOM 节点仍驻留内存。
- 每次重新渲染前，先调用
mermaid.unregisterAll()清除旧实例注册表 - 监听
webview.onDidDispose或editor.onDidCloseTextDocument，主动执行document.querySelectorAll('svg.mermaid').forEach(el => el.remove()) - 避免在
subgraph内使用click语法绑定跳转——它会为每个节点注入addEventListener，改用全局事件委托（svg.addEventListener('click', handler)）
Webview 环境下 Mermaid 渲染线程阻塞
VSCode Webview 默认运行在 UI 线程，Mermaid 解析长文本（如含 50+ 代码块的 classDiagram）会直接冻结编辑器响应。
- 把解析逻辑移出主线程：用
Worker执行mermaid.parse()，只将生成的svgStringpost 回主线程插入 - 禁用 Webview 中的
mermaid.init()自动启动，改用显式mermaid.render(id, text, cb)控制时机 - 对超长图表（>1000 行源码）启用分块加载：先渲染骨架，再用
setTimeout分批注入子图，避免 JS 调用栈溢出
真正卡住 Mermaid 的从来不是语法复杂度，而是你没切断它和 VSCode 渲染管线之间的隐式耦合——比如默认开启的 clickDrag 模式会在每个节点上挂 3 个事件监听器，而你其实只用了其中 1 个。
