根本原因是插件未启用自动刷新或配置错误；需确认安装Markdown All in One、开启markdown.extension.toc.updateOnSave为true、确保唯一[TOC]标记，失效时手动执行Update Table of Contents命令。
为什么 Markdown 目录总不自动更新
根本原因不是插件没装，而是默认不监听标题变更。比如你改了 # 新章节，但目录没变，大概率是插件没启用自动刷新，或者你用的是不支持实时更新的老版本插件。
实操建议：
- 确认已安装
Markdown All in One（不是Markdown TOC，后者不支持保存即刷新） - 检查设置中是否启用了
markdown.extension.toc.updateOnSave，值必须为true - 确保文档里有且仅有一个
[TOC]标记——多写一个或拼错成[toc]都会导致失效 - 如果改完标题后仍不更新，手动按
Ctrl+Shift+P→ 输入Markdown: Update Table of Contents强制刷新一次，看是否生效
如何让目录只包含 H2 和 H3 级标题
默认生成的目录会把所有 # 到 ###### 都塞进去，实际项目里往往只需要二级和三级结构，比如 API 文档的模块 + 接口列表。
实操建议：
- 在
settings.json中添加："markdown.extension.toc.levels": "2..3" - 注意语法：不能写成
"2-3"或"2,3"，必须用两个点号.. - 如果同时想用有序列表，加一行：
"markdown.extension.toc.orderedList": true - 改完保存，再执行一次
Markdown: Create Table of Contents或重新保存文件
侧边浮动目录面板怎么开
Markdown All in One 本身不提供侧边目录，但配合 Markdown Preview Enhanced 就能实现——而且它支持滚动同步高亮，比静态 TOC 实用得多。
实操建议：
- 卸载
Markdown All in One的预览功能（避免冲突）：在设置中关掉markdown.preview.doubleClickToSwitchEditor - 安装
Markdown Preview Enhanced，重启 VSCode - 打开任意
.md文件，右键 →Markdown Preview Enhanced: Open Preview to the Side - 预览窗口右上角点击
⋯→Toggle Table of Contents，即可固定侧边栏 - 滚动正文时，目录项会自动高亮当前所在章节
目录链接跳转失败常见原因
点击目录里的 [简介](#简介) 却跳不到对应标题，基本不是插件问题，而是标题 ID 生成规则被破坏了。
实操建议：
- 中文标题会被转成小写、去标点、空格变短横线，例如
## 第一章：快速入门！→#第一章快速入门，所以链接必须匹配这个 ID - 避免在标题里用
+、&、®等特殊字符，它们可能被过滤或编码异常 - 如果标题以数字开头（如
1. 安装步骤），部分渲染器会忽略，建议加个字母前缀：1-安装步骤 - 检查是否启用了
markdown.extension.toc.slugifyMode，推荐设为github（兼容 GitHub 渲染）
真正卡住人的，往往是标题 ID 和链接之间那层看不见的映射关系——它不报错，只静默失效。调目录时，先看预览里生成的链接 href 是什么，再对比目标标题实际生成的锚点，差一个字符就跳不动。
