90%锚点点击无反应是因目标元素缺失id、id不合法或存在同名name属性；需确保id全小写、仅含字母数字和短横线、全局唯一，且href与id值严格一致。
为什么直接写 <a href="#xxx"></a> 常常点不动
90% 的“点击无反应”不是 JS 问题，而是锚点链路断在底层：目标元素没 id、id 值不合法、或页面存在同名 name 属性（尤其旧表单里残留的 <input name="top">）。浏览器静默失败，不报错也不滚动。
验证方法很直接：手动修改地址栏 URL，比如改成 #setup-env，看是否滚动；再右键检查目录链接的 href 值，是否和目标 <h2 id="setup-env"></h2> 完全一致（大小写、连字符、无空格）。
-
id必须全小写、只含字母数字和短横线（-），不能以数字开头（id="1-intro"→ 改为id="intro-1"） - 中文标题要转义：
"用户登录流程"→textContent.trim().replace(/[^a-z0-9\u4e00-\u9fa5]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() - 同一页面内所有
id必须全局唯一；重复会导致跳转总落到第一个匹配项
用 document.querySelectorAll('h2, h3') 动态生成目录时踩的坑
脚本跑得比 DOM 快，是新手最常忽略的前提。如果没等 DOM 加载完就执行 document.querySelectorAll('h2, h3')，返回的是空数组——目录根本没内容。
生成逻辑本身不难，但细节决定成败：
立即学习“前端免费学习笔记（深入）”；
- 必须在
DOMContentLoaded或load事件后运行，React/Vue 用户注意在useEffect或mounted钩子中初始化 - 遍历时别只取
textContent，用el.textContent.trim()避免空标题生成id=""→ 最终变成href="#undefined" - 插入目录别用循环
appendChild，改用toc.innerHTML = htmlString，避免频繁重排卡顿 - 层级关系靠
el.tagName判断：H2生成一级项，H3缩进为子项；若 HTML 出现h2 → h4 → h3，h4被跳过，h3会错误挂到上一个h2下
滚动到目标位置却卡在顶部被导航栏挡住
这是固定头部（position: fixed 或 sticky）导致的典型偏移问题。scrollIntoView 默认把目标元素顶到视口最上方，结果被遮住一半。
修复方式分两层：
- CSS 层加
scroll-margin-top：给所有标题加h2, h3 { scroll-margin-top: 64px; }（数值按你的导航栏高度调整） - JS 层调用时加偏移参数：
el.scrollIntoView({ behavior: "smooth", block: "start" })，IE 不支持behavior: "smooth"，需降级为"auto" - 如果用
history.pushState更新 URL，记得同步触发scrollIntoView，否则前进/后退不会自动滚动
目录项如何随滚动自动高亮
:target 只能高亮当前 URL hash 对应的元素，无法反映“哪个标题正在视口顶部”，所以必须用 IntersectionObserver。
关键配置容易错：
- 阈值设成
[0.1]（10% 进入视口即触发），比[0]更稳定，避免快速滚动时漏判 -
rootMargin: "-50px 0px 0px 0px"模拟向上偏移，让标题还没完全进入视口时就高亮（配合scroll-margin-top使用） - 不要对同一个元素多次调用
observer.observe(el)，否则观察器状态异常且不报错 - 高亮逻辑必须用 JS：拿到
entries[0].target.id后，去匹配目录中href="#xxx"的<a></a>并加 class，CSS 仅负责样式
真正麻烦的不是写几行代码，而是确保所有标题在观察器初始化前已真实存在于 DOM 中——动态渲染内容（如 Markdown 解析后插入）必须等解析完成再创建 observer。
