用 JavaScript 自动提取 h2/h3 生成目录：先用 document.querySelectorAll('h2, h3') 获取标题，为空 id 时按文本生成合法唯一 id，构建带 #href 的 a 标签插入 nav；配合 scroll-margin-top 避让固定头部，用 IntersectionObserver 高亮当前章节，服务端留空容器防 hydration mismatch。
如何用 JavaScript 自动提取 <h2> 和 <h3> 生成目录
浏览器原生不支持自动生成文章目录，必须靠 JS 扫描 DOM 中的标题标签并构建列表。关键不是“能不能”，而是“扫哪些、怎么挂载、怎么跳转”。<h1> 通常作主标题，不进目录；<h2> 作为一级章节，<h3> 作为子节，这是最通用且语义合理的分层。
实操建议：
- 用
document.querySelectorAll('h2, h3')获取所有目标标题，按出现顺序遍历 - 为每个标题动态生成
id（若原本没有）：取文本内容 → 去空格/标点 → 小写 → 连字符连接，例如"事件循环机制"→"shijian-xunhuan-jizhi" - 目录项用
<a href="#xxx">指向对应id，确保页面内跳转可用 - 注意：中文文本直接用
textContent提取，别用innerText（可能触发重排）
点击目录后滚动不准？检查 scroll-margin-top 是否设置
现代浏览器点击锚点会默认滚动到元素顶部，但若页面有固定头部（position: fixed），标题会被遮挡。这不是 JS 逻辑问题，而是 CSS 滚动定位偏差。
解决方式很简单：
立即学习“前端免费学习笔记（深入）”；
- 给所有标题加统一 CSS：
h2, h3 { scroll-margin-top: 60px; }（数值按头部高度调整） - 不要用 JS 的
scrollIntoView({ behavior: 'smooth' })替代锚点跳转——它不更新 URL hash，也不触发浏览器前进/后退记录 - 若需兼容旧版 Safari（
scroll-margin-top支持较晚），可 fallback 到scrollIntoView+ 手动修正window.scrollY
IntersectionObserver 动态高亮当前章节的原理和坑
目录高亮不是靠监听 scroll 事件算位置，而是用 IntersectionObserver 观察标题是否进入视口。它更轻量、不阻塞主线程，但默认阈值（threshold: 0）容易误判。
推荐配置：
- 设
threshold: [0.1]，表示标题顶部 10% 进入视口即触发 - 观察目标是
h2和h3，但只对h2做高亮（h3高亮逻辑复杂且干扰主路径） - 每次回调中，取第一个
isIntersecting === true的h2，将其id同步到目录中对应<a>的class="active" - 避免在回调里直接操作 DOM 样式（如
el.style.color），统一走 class 切换，方便维护 CSS
服务端渲染（SSR）或静态站点中如何避免水合 mismatch
Vue/React 项目若在服务端预渲染目录，而客户端 JS 又重新生成一遍，会导致 DOM 不一致、React 报 warning、Vue 警告 hydration failed。根本原因在于服务端无法执行 JS 提取标题，目录为空，客户端补上后结构突变。
稳妥做法：
- 服务端完全不生成目录 HTML，只留一个空容器，比如
<nav id="toc" class="toc-placeholder"></nav> - 客户端 JS 检查
document.getElementById('toc').children.length === 0再执行生成逻辑 - 若用 Astro / Next.js / Nuxt 等框架，把目录逻辑放在
useEffect或onMount中，确保只在浏览器端运行 - 别试图在服务端用正则解析 HTML 字符串提取标题——HTML 结构多变，
<h2>可能跨行、含内联元素、被注释包裹，极易出错
真正麻烦的从来不是生成目录，而是让滚动定位、高亮响应、服务端协作这三件事不互相打架。每个环节都看似简单，叠在一起就容易漏掉 scroll-margin、observer 阈值、hydration 时机中的某一个。
