vscode markdown卡顿主因是扩展冲突、配置不当及大文件渲染过载；应禁用冗余扩展、设decorationfilesizelimit限语法装饰、关autopreview防实时渲染、选对katex/mathjax引擎并配准路径与delimiters。
VSCode 的 Markdown 渲染本身不卡，卡的是你装的扩展、写的配置、打开的文件，以及没关掉的预览窗口。
为什么预览一滚动就卡顿？看 CPU 占用和扩展冲突
真实场景：编辑一个 2000 行的 README.md，右侧预览一滚动就延迟半秒，光标跟丢，甚至整个 VS Code 假死。
这不是 VSCode 问题，而是渲染链路被拖慢了。关键排查点：
- 执行
Developer: Reload with Extensions Disabled，只留Markdown All in One和Markdown Preview Enhanced，再试滚动 —— 如果变流畅，说明其他扩展（尤其是拼写检查、自动保存、GitLens 的某些钩子）在后台高频扫描 Markdown 内容 - 打开
Help > Toggle Developer Tools > Performance，录一段滚动操作，看火焰图里耗时大户是不是markdown.extension.syntax.*或previewEnhanced.render - 检查是否启用了
markdown.extension.toc.autoUpdate，它会在每次光标移动时重解析全文生成目录 —— 对大文件就是定时卡顿器
大文件直接不渲染语法装饰，但保留预览功能
VSCode 默认对所有 Markdown 文件启用语法高亮、链接跳转、TOC 生成等“装饰”，但这些在 >50KB 的文件里会显著拖慢响应。不是禁用扩展，而是精准关闭冗余能力：
- 在
settings.json中加这一项："markdown.extension.syntax.decorationFileSizeLimit": 100000（单位字节），超过即跳过语法装饰，但预览、导出、代码块高亮照常工作 - 如果连预览都卡，说明是
Markdown Preview Enhanced的实时渲染在作祟 —— 关掉"markdown-preview-enhanced.autoPreview": false，改用手动触发Markdown Preview Enhanced: Open Preview to the Side - 避免同时开多个预览窗口，每个窗口都是独立 WebView 实例，内存和 GPU 资源叠加消耗
公式渲染选 KaTeX 还是 MathJax？别只看文档推荐
选错引擎不会报错，但会导致你反复刷新、怀疑配置、删插件重装 —— 实际只是渲染策略不匹配当前场景：
-
"markdown-preview-enhanced.mathRenderingOption": "KaTeX"：适合日常技术文档、博客草稿。启动快、无网络依赖、行内公式基线对齐好；但不支持\cancel、\align等高级宏，遇到就原样显示 -
"markdown-preview-enhanced.mathRenderingOption": "MathJax"：学术写作必需。支持完整 LaTeX 宏包，但首次加载要下载 JS、解析慢、高 DPI 下 SVG 公式偶尔模糊 —— 若发现公式边缘发虚，加配置"markdown-preview-enhanced.mathjaxV3ScriptSrc": "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"换 CDN - 别混用：
mathInlineDelimiters和mathBlockDelimiters必须与所选引擎一致，KaTeX 不认\[ ... \]，MathJax 默认不启用$...$行内模式，得手动配
自定义 CSS 注入后样式不生效？检查路径和作用域
你写了很漂亮的 styles.css，也配了 "markdown.styles": ["styles.css"]，但标题字体还是默认大小 —— 问题几乎全出在路径或选择器权重上：
-
"markdown.styles"只对 VS Code 内置预览生效，对Markdown Preview Enhanced的预览无效；后者要用"markdown-preview-enhanced.customStyles": ["styles.css"] - CSS 文件必须放在工作区根目录（即你按
Ctrl+K Ctrl+O打开的那个文件夹），不能放在子目录，也不能用相对路径如./css/styles.css - VS Code 预览 WebView 是隔离环境，
body选择器可能被插件内联样式覆盖，优先用更具体的选择器，比如.markdown-preview-body h1或webview body h1
真正影响体验的从来不是“有没有功能”，而是“哪个开关在哪关、哪个值设多少、哪条路径不能错”。尤其当多个扩展共存时，一个配置项的微小偏差，就会让渲染从丝滑变成幻灯片。
