Scrollspy在Bootstrap 5中默认不自动激活，必须满足三个前提：data-bs-spy="scroll"加在滚动容器（如body或overflow-y:auto元素）上、目标section的id与导航href严格匹配、滚动容器需有明确高度和溢出设置。
Scrollspy 在 Bootstrap 5 中默认不自动激活导航项，必须手动确保 DOM 结构、ID 匹配和初始化时机都正确，否则 data-bs-spy="scroll" 会静默失效。
必须满足的三个前提条件
Scrollspy 不是“加个属性就跑”，它依赖严格的上下文约束：
-
data-bs-spy="scroll"必须加在**滚动容器**上（通常是<body>或带overflow-y: auto的元素），不是加在导航栏上 - 目标区域（section）的
id必须与导航链接的href完全一致（例如href="#about"→ 对应<section id="about">） - 滚动容器必须有明确高度（
<body>需设height: 100vh或类似；自定义容器需设height+overflow-y: auto）
offset 和 smooth scrolling 的协同问题
当导航栏固定在顶部时，滚动到目标区域顶部会被遮挡——offset 就是用来补偿这个偏移量的，但它只影响 Scrollspy 的激活判断，不影响原生滚动行为：
- 用
data-bs-offset="72"（假设导航栏高 72px）让 Scrollspy 在目标距视口顶部 72px 时就标记为“活跃” - 但页面滚动本身仍会停在
id元素顶部，要实现真正平滑且对齐的滚动，还需额外加 CSS：html { scroll-behavior: smooth; } - 如果用了 JavaScript 滚动（如
element.scrollIntoView()），得手动传入{ block: 'start', behavior: 'smooth' }并减去 offset 值
JavaScript 初始化时容易漏掉的细节
如果用 JS 初始化 Scrollspy（而非 data 属性），以下三点极易出错：
- 目标容器（
target）必须是**已挂载的 DOM 节点**，不能是字符串选择器（Bootstrap 5 不支持字符串 target） -
offset参数单位是像素（数字），不是字符串：{ offset: 72 }✅，{ offset: "72" }❌ - 若页面内容动态加载（如 AJAX 插入 section），需手动调用
scrollSpyInstance.refresh()重新扫描 DOM
const navbar = document.querySelector('#navbar');
const scrollSpy = new bootstrap.ScrollSpy(document.body, {
target: '#navbar',
offset: 72
});
常见失效现象与快速排查路径
导航项始终不加 active 类？先检查这四点：
- 浏览器控制台是否报错
Bootstrap's scrollspy requires a scrollable container？→ 确认滚动容器有高度+溢出设置 - 点击导航链接能否跳转？不能 →
id和href不匹配，或目标元素未渲染 - 滚动时
active类闪烁或错位 →offset值小于实际导航栏高度，或目标 section 高度太小（建议最小高度 ≥ viewport 高度） - 使用了第三方库（如 Turbolinks、Barba.js）→ 它们会替换 body，导致 Scrollspy 实例绑定失效，需在每次页面切换后重建实例
Scrollspy 的核心逻辑其实很朴素：监听滚动，计算每个 id 元素的视口位置，再比对 offset。真正卡住人的，永远是那些看不见的 DOM 约束和样式副作用。
