Bootstrap 5 ScrollSpy 默认仅监听 window/body，若用于局部滚动容器需显式传入容器元素、设置 rootMargin 为负百分比，并确保 DOM 结构符合同级或子级要求，同时注意 id 精确匹配、移动端兼容及动态内容后手动 refresh。
Bootstrap 5 的 ScrollSpy 默认不支持非
如果你把滚动区域设在某个 <div class="scrollable"> 里（比如侧边栏或内容区局部滚动），直接初始化 <code>ScrollSpy 会失效——它默认只监听 window 或 document.body。必须显式传入 target 和 rootMargin，且容器需有 position: relative 或 overflow-y: auto 并设固定高度。
- 错误写法：
new bootstrap.ScrollSpy(document.body, { target: '#navbar' })→ 只对全页滚动有效 - 正确写法：
new bootstrap.ScrollSpy(scrollContainer, { target: '#navbar', rootMargin: '0px 0px -30% 0px' })，其中scrollContainer是带overflow-y: auto的 DOM 元素 -
rootMargin推荐设为负百分比（如-30%），避免因导航栏遮挡导致高亮滞后；纯像素值（如'0px 0px -100px 0px'）在响应式下易失准
data-bs-spy 属性 + data-bs-target 必须指向同一 DOM 树层级
用 HTML 属性方式启用时，data-bs-spy="scroll" 的元素必须是滚动容器本身，且 data-bs-target 指向的导航菜单必须是它的**同级或子级**，不能跨父容器。例如：
<div data-bs-spy="scroll" data-bs-target="#sidebar-nav" data-bs-offset="0" tabindex="0"> <div id="content">...</div> </div> <nav id="sidebar-nav"></nav> <!-- ❌ 失败：#sidebar-nav 不在 data-bs-spy 元素内部 -->
改成：
<div data-bs-spy="scroll" data-bs-target="#sidebar-nav" ...> <nav id="sidebar-nav"></nav> <div id="content">...</div> </div>
- 若导航栏在
<header></header>里、内容在<main></main>，就不能用纯属性方式，得用 JS 初始化并手动绑定 -
data-bs-offset值建议设为0，靠rootMargin控制触发时机更可靠
楼层元素必须有 id，且导航链接 href 必须严格匹配
ScrollSpy 通过 a[href="#section-id"] 与目标 <section id="section-id"></section> 的 id 做字符串精确匹配，大小写、连字符、下划线全部敏感。
- 合法：
<a href="#contact-us">联系我们</a>→ 对应<section id="contact-us"></section> - 非法：
<a href=".contact-us"></a>（类选择器）、<a href="/#about"></a>（带路径）、<a href="#About"></a>（大小写错） - 动态生成的楼层（如 Vue/React 渲染），确保
id在挂载后真实存在于 DOM，否则初始化时找不到目标
移动端 Safari 下 ScrollSpy 常静默失败
iOS Safari 对局部滚动容器的 scroll 事件触发不敏感，尤其当容器使用 -webkit-overflow-scrolling: touch 时。此时 ScrollSpy 可能完全不响应。
- 临时方案：移除
-webkit-overflow-scrolling，改用原生滚动（牺牲惯性，但功能正常） - 稳妥方案：降级为手动监听
scroll事件 +getBoundingClientRect()计算可见性，绕过ScrollSpy：
scrollContainer.addEventListener('scroll', () => {
const sections = document.querySelectorAll('section[id]');
const scrollPos = scrollContainer.scrollTop + 100; // 补偿偏移
let current = '';
sections.forEach(sec => {
if (sec.offsetTop <= scrollPos && sec.offsetTop + sec.offsetHeight > scrollPos) {
current = '#' + sec.id;
}
});
document.querySelectorAll('#navbar a').forEach(a => {
a.classList.toggle('active', a.getAttribute('href') === current);
});
});真正麻烦的不是写法，而是当楼层高度动态变化（比如图片懒加载完成、折叠面板展开）后，ScrollSpy 不会自动重算位置——你得手动调用 refresh()，或者监听 load / resize 后主动触发。
