原生 window.scrollto({ top: 0, behavior: 'smooth' }) 即可实现返回顶部，但必须设置 html { scroll-behavior: smooth; }（safari 需加 -webkit 前缀），否则平滑滚动静默失效；按钮需防默认跳转并补偿 fixed-top 导航栏高度，滚动监听应读 document.documentelement.scrolltop 并节流。
原生 window.scrollto({ top: 0, behavior: 'smooth' }) 就够了，bootstrap 本身不提供“返回顶部”功能，也不该依赖 jquery 动画或 bootstrap js 插件——加了反而容易和 scrollspy、navbar 等逻辑冲突。
必须设置 html { scroll-behavior: smooth; }
这是最常被跳过的一步。哪怕 JS 调用完全正确，只要这行 CSS 缺失，behavior: 'smooth' 就会静默退化为瞬间跳转。
-
body { scroll-behavior: smooth; }无效，必须作用在html元素上 - 旧版 Safari（iOS 15.3 及更早）需额外加
-webkit-scroll-behavior: smooth; - 如果已引入第三方平滑滚动库（如
smooth-scroll），优先移除，避免与原生行为冲突
按钮点击时要防默认跳转和导航栏遮挡
直接写 href="#top" 或用 onclick="window.scrollTo()" 不拦默认行为，页面会先闪一下跳到锚点，再执行滚动——体验极差。
- 推荐用
<button type="button" id="back-to-top">回到顶部</button>，从语义上避开锚点跳转 - 若仍用
<a href="#top"></a>，事件监听中必须调用event.preventDefault() - 有
.fixed-top导航栏时，不能只滚到top: 0：要动态补偿高度，例如const offset = document.querySelector('.fixed-top')?.offsetHeight || 0; window.scrollTo({ top: -offset, behavior: 'smooth' });
按钮显隐逻辑要兼容 Safari 和节流
监听 window.scroll 是必须的，但获取滚动高度的方式在 Safari 下容易出错。
- 别用
document.body.scrollTop：Safari 常返回0，应优先读document.documentElement.scrollTop - 快速滚动时频繁触发会影响性能，建议用
requestAnimationFrame节流，或简单用setTimeout(..., 16)防抖 - 不要用
element.getBoundingClientRect().top判断是否显示按钮——它反映的是元素相对于视口的位置，不是页面整体滚动状态
真正难的不是写那三行 JS，而是意识到：所有“平滑”都得自己补；而最容易失效的环节，往往藏在那一行不起眼的 html { scroll-behavior: smooth; } 里。
