核心是建立滚动位置与目录项的稳定映射关系，需正确配置threshold（必须为数组）、rootmargin协同scroll-margin-top、id严格一致且预生成、高亮更新须节流并分离状态与dom操作。
用 IntersectionObserver 做目录高亮，核心不是“让某个标题变色”，而是建立「滚动位置 ↔ 目录项」的稳定映射关系。直接监听所有 h2/h3 并在回调里改 classList，90% 的人会遇到高亮错位、跳变、卡顿或点击后不更新的问题——根源在阈值、偏移、观察时机和 DOM 同步没对齐。
为什么 threshold: [0.1] 比 [0] 更可靠
设为 [0] 时，只要元素像素级擦过视口顶部（哪怕只露 1px），就触发 isIntersecting: true。但滚动惯性下，多个标题可能在极短时间内连续满足该条件，导致高亮频繁切换；而 [0.1] 要求至少 10% 高度进入视口，天然过滤掉“擦边”干扰，更贴近用户“当前看到的是哪一节”的直觉。
常见错误是写成 threshold: 0.1（单数值）。浏览器虽会自动转为 [0.1]，但语义模糊，调试时容易误判逻辑。必须显式写成数组。
-
threshold: [0, 0.1, 0.5]会触发三次回调，通常没必要，反而增加判断负担 - 若正文有大量短标题（如
h4），建议只观察h2和h3，避免观察节点过多拖慢 Observer 初始化 - 不要用
getBoundingClientRect()在回调里反复计算——这是旧方案卡顿的主因，IntersectionObserver已把位置信息算好放在entry.boundingClientRect里
rootMargin: "-64px 0px 0px 0px" 是为了绕过固定头部遮挡
当页面顶部有 position: sticky 导航栏（高度 64px）时，scrollIntoView 或默认锚点跳转会把标题顶到视口最上方，结果被导航栏盖住。很多人用 margin-top: -64px + padding-top: 64px 补偿，但这样会破坏文档流，影响打印样式和无障碍阅读。
正确做法是两处配合：
- CSS 层：给目标标题加
scroll-margin-top: 64px（例如h2 { scroll-margin-top: 64px; }），告诉浏览器“这个元素的‘可定位顶部’应该往下偏移 64px” - JS 层：在
IntersectionObserver的rootMargin中写"-64px 0px 0px 0px"，让 Observer 的“视口顶部”也上移 64px，确保它和scroll-margin-top对齐 - 二者缺一不可。只设 CSS 不改
rootMargin，Observer 仍按原始视口判断，高亮会滞后；只改rootMargin不设 CSS，点击跳转仍会被遮挡
目录项和正文标题的 ID 必须严格一致且可预测
目录 HTML 写成 @#@#@#@#@#@#@#@#@#@0，对应正文就必须是 <h2 id="an-zhuang-bu-zhou">安装步骤</h2>。不能靠 JS 动态拼接 ID，也不能用序号（如 section-1）或文本内容（如 encodeURIComponent("安装步骤")）生成——服务端渲染（SSR）和客户端渲染（CSR）环境可能生成不同 ID，导致点击跳转失败或高亮失联。
推荐方案：
- 服务端或构建时统一用 slugify 处理中文/空格/符号，例如
"快速开始 → kuai-su-kai-shi" - 目录项的
href和正文id必须来自同一份数据源（如 Markdown frontmatter 或 CMS 字段） - 避免使用
data-id或自定义属性做映射——增加一层解析，出错概率翻倍
高亮更新必须节流，且不能在 Observer 回调里直接操作 DOM
IntersectionObserver 回调是异步的，但高频滚动时仍可能每秒触发多次。如果每次都在回调里执行 document.querySelector(...).classList.add(...)，会强制浏览器同步重排，尤其在低端设备上明显卡顿。
安全做法是把“状态记录”和“DOM 更新”分离：
- 回调中只做一件事：找出当前
intersectionRatio最大的那个entry，存入变量currentActiveId - 用
requestIdleCallback或简单节流（如setTimeout(..., 0)）把实际的 class 切换延迟到空闲帧执行 - 更新前先比对
currentActiveId是否变化，避免无意义的 DOM 写操作
真正难的不是监听，而是让高亮“稳得住”：不抖、不错位、不抢资源。很多项目卡在这里，是因为把 IntersectionObserver 当成了万能开关，忽略了它只是个信号源——后续的状态同步、样式生效、历史记录更新，都得自己闭环。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
