VSCode中Markdown实时渲染：处理公式插件导致的运行卡顿

MathJax渲染卡顿主因是同步加载+未节流重渲染+重复初始化；应选KaTeX引擎、显式禁用降级与MathJax脚本、配置mathTypesetDelay防抖，并禁用冲突插件如Markdown All in One的数学功能。

公式插件不是必须关掉，而是得选对引擎、配对参数、避开默认陷阱——卡顿往往来自 MathJax 同步加载 + 未节流的重渲染 + 重复初始化。

为什么 MathJax 渲染一开就卡？

MathJax v3 默认采用同步脚本加载 + 全文档扫描模式，每次预览更新都会重新解析所有 $ 和 $$ 区块，遇到长文档或嵌套公式时 CPU 占用飙升。更麻烦的是，Markdown Preview Enhanced 在未配置防抖时，每敲一个字符都触发一次 MathJax 重排，浏览器主线程直接被锁死。

• 典型现象：Ctrl+K V 打开预览后，滚动卡顿、光标延迟、退格键响应慢 2 秒以上
• 检查方法：打开开发者工具（Ctrl+Shift+I），切到 Performance 面板录一段输入操作，看是否大量 MathJax.typeset() 调用堆叠
• 根本原因：不是 MathJax 本身慢，而是它被放在主线程里反复调用，且没做内容变更比对

换 KaTeX 就能立刻变快？

能，但得关掉自动降级开关。KaTeX 是纯函数式、零依赖、编译型渲染器，天生适合实时场景。不过 markdown-preview-enhanced 默认启用 mathRenderingOption: "KaTeX" 时，仍可能 fallback 到 MathJax —— 只要检测到某个公式 KaTeX 不支持（比如 cancel 或自定义宏），就会整页切回 MathJax。

• 必须显式关闭降级："markdown-preview-enhanced.mathRenderingOption": "KaTeX" + "markdown-preview-enhanced.katexAutoRender": true
• 禁用 MathJax 加载：在设置中清除 markdown-preview-enhanced.mathjaxV3ScriptSrc，避免插件偷偷拉取 MathJax 脚本
• 注意兼容边界：KaTeX 不支持 label/ref 交叉引用，也不支持 newcommand 动态定义，复杂论文慎用

如何让公式只在需要时才渲染？

核心是「按需触发」+「差异更新」。别让插件一打开就扫全文，而是等用户滚动到公式附近、或聚焦到含公式的段落时再启动渲染。这需要两层控制：

• 在 settings.json 中启用节流："markdown-preview-enhanced.mathTypesetDelay": 300（单位毫秒，防抖阈值）
• 配合 CSS 控制可视区渲染：pre[class*="language-math"] { opacity: 0.3; } + JS 监听 IntersectionObserver，仅当公式进入视口才调用 katex.render()
• 禁用全局监听：把 "markdown-preview-enhanced.enableScriptExecution": false，防止插件执行任意 JS 干扰主线程

插件冲突导致的隐性卡顿怎么揪？

最常踩的坑是 Markdown All in One 和 Markdown Preview Enhanced 同时启用数学支持。前者会注册 onBackspaceKey，后者又监听 contentChanged，两个插件对同一段公式文本反复解析，结果就是输入延迟翻倍。

• 验证方式：运行 Developer: Show Running Extensions，看是否有多个扩展同时报告高 CPU 使用率
• 清理方案：保留 Markdown Preview Enhanced（它负责预览+公式），禁用 Markdown All in One 的公式相关功能："markdown.extension.math.enabled": false
• 额外检查点：确认没有其他插件注入 <script></script> 标签（比如某些 SEO 插件），它们可能干扰 MathJax/KaTeX 初始化流程

真正影响体验的从来不是“有没有公式”，而是“谁在什么时候、以什么方式、对哪段内容做了多少次重复计算”。删插件不如理清数据流，关功能不如切断冗余链路。