根本原因是插件默认仅在保存文件时触发更新，而非实时响应编辑；需确保存在标准[TOC]占位符、光标不在其内，并重启预览窗口以应用"markdown.extension.toc.levels": "2..4"等配置，同时注意中文标题锚点编码匹配与硬件加速启用。
为什么 Markdown 目录总不自动更新？
根本原因不是插件没装，而是你没用对触发机制。比如 Markdown All in One 插件默认只在保存文件（Ctrl+S）时重新生成目录——如果你只是改了标题但没保存，预览里看到的还是旧目录。
常见错误现象包括：
- 修改了
## 新章节，但目录里仍显示旧标题 - 插入新标题后，目录没新增条目
- 点击目录链接跳转失败，提示“无法定位到锚点”
解决办法很直接：
- 确保文档中存在有效的
[TOC]占位符（不是[[TOC]]或其他变体） - 保存文件前，确认光标不在
[TOC]区域内（否则可能被当成普通文本编辑） - 如果仍不生效，手动调用命令：
Ctrl+Shift+P→ 输入Create Table of Contents再执行一次
如何让目录只包含 H2–H4，跳过 H1 和 H5？
默认行为是把所有 # 到 ###### 都拉进来，但技术文档通常不需要展示项目级标题（H1）或细节小节（H5/H6）。靠插件配置就能精准控制。
Markdown All in One 支持通过 settings.json 设置：
-
"markdown.extension.toc.levels": "2..4"—— 注意是字符串格式，不是数字数组 - 该配置会忽略
#和#####/######，只提取##、###、#### - 如果用了
Markdown Preview Enhanced，对应配置项是"markdown-preview-enhanced.tocLevels"
别漏掉一点：改完配置必须重启预览窗口（关闭再打开 Markdown 预览页），否则新规则不生效。
目录链接跳转失效，是不是路径编码问题？
是。中文标题、带空格或特殊符号（如 +、/、&）的章节名，在生成锚点时会被 URL 编码，但部分插件生成目录时没同步处理，导致跳转 404。
典型表现：
- 标题写的是
## 数据导出与清洗，目录生成的链接却是[数据导出与清洗](#数据导出与清洗)（未编码） - 实际锚点 ID 是
data-chu-ru-yu-qing-xi或%E6%95%B0%E6%8D%AE%E5%AF%BC%E5%87%BA%E4%B8%8E%E6%B8%85%E6%B4%97
应对方式：
- 优先用英文+短横线命名标题，如
## data-export-and-cleaning - 若必须用中文，确认插件版本 ≥ v3.4.0（
Markdown All in One自 v3.4.0 起统一使用 GitHub 风格锚点生成逻辑） - 临时验证方法：右键点击标题 → “Copy Link Address”，粘贴出来看实际锚点是否匹配目录里的
href
侧边浮动目录面板卡顿或不显示？
这不是插件坏了，大概率是 VSCode 渲染层在处理大量标题时的性能阈值被触发。尤其当文档超过 200 行、标题层级深且数量多（比如自动生成的 API 文档），浮动面板会主动降级为静态列表甚至隐藏。
能立刻缓解的操作：
- 在设置里关掉
markdown.extension.toc.followCursor（滚动跟随功能最耗资源） - 限制目录深度：
"markdown.extension.toc.levels": "2..3"，减少节点数量 - 避免在单个文件里塞进 50+ 个
###级标题——拆成多个子文档更实际
真正容易被忽略的一点：浮动面板依赖 VSCode 的 WebView 渲染，如果你禁用了硬件加速（--disable-gpu 启动参数），它根本不会出现。检查启动方式，别为了省内存关掉这个底层能力。
