必须用<button>而非或<div>，因其语义正确、键盘可聚焦、屏幕阅读器可识别，且需设唯一id和aria-label以满足WCAG 2.1强制要求。
按钮必须用 <button>，不能用 <a> 或 <div>
语义错误是最大隐患：用 <a href="#top"> 会触发 URL 哈希变化、可能干扰前端路由；用 <div> 则键盘不可聚焦、屏幕阅读器无法识别。真实项目里被测出无障碍问题的，八成栽在这儿。
正确结构只有一套：<button id="backToTop" aria-label="返回顶部">↑</button>id 必须唯一；aria-label 不可省略——它不是“锦上添花”，而是 WCAG 2.1 强制要求。
别把按钮塞进页脚或某个 <section> 里再靠 CSS 定位，它得直接挂在 <body> 内层（比如紧贴 </body> 前），否则固定定位失效或被父级 overflow: hidden 截断。
window.scrollTo({ top: 0, behavior: 'smooth' }) 是唯一推荐调用方式
写 window.scrollTo(0, 0) 或 document.documentElement.scrollTop = 0 都是硬跳，用户感知差；用 scrollIntoView() 又依赖目标元素存在且可见（比如 display: none 的锚点会让它静默失败）。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
必须显式传对象参数：window.scrollTo({ top: 0, behavior: 'smooth' })
漏掉 behavior: 'smooth' 就等于没写——Safari 15.4+ 和 Chrome/Edge 都支持，但旧安卓 WebView 会回退为瞬时滚动，这是正常降级，不是 bug。
注意两点：
• 在 iframe 里调用需同源，否则抛 SecurityError
• 不要混搭：比如先设 scrollTop = 0 再调 scrollIntoView()，行为不可控
显隐逻辑别只靠 window.scrollY > 300 硬判断
阈值设 300px 是常见做法，但首屏高度千差万别：移动端小屏下 300px 可能已过半屏，PC 大屏下又显得太迟钝。更稳妥的是用 innerHeight * 0.6 动态计算。
监听本身也有坑：
• 别用 document.body.scrollTop —— 在 Chrome/Firefox 下它常为 0，只在某些 IE 模式下有效
• 统一读 window.scrollY（现代标准）或 window.pageYOffset（兼容性更广）
• 首次加载后必须手动调用一次显隐函数，否则刷新页面按钮状态错乱
性能上，scroll 事件高频触发，建议加节流（如用 requestAnimationFrame 包一层），或者直接上 IntersectionObserver 监听顶部占位元素是否出视口——后者不卡顿、天然防抖，适合长列表页。
CSS 定位和 z-index 容易被忽略的细节
按钮必须用 position: fixed，但仅此不够：
• bottom 和 right 值要留安全区余量（比如 bottom: env(safe-area-inset-bottom, 20px)），否则 iOS 底部横条会遮挡
• z-index 至少设为 100，很多 UI 框架（如 Ant Design、Element Plus）的弹窗 z-index 是 99 或 2000，设低了会被盖住
• 别用 visibility: hidden 控制显隐——它仍占布局空间，固定定位会偏移；坚持用 display: none 或 opacity: 0; pointer-events: none
缩放页面（Ctrl + “+”）时，固定定位按钮可能错位，加一句 transform: translateZ(0) 可强制 GPU 加速修复；横向滚动页面时，right: 20px 会随文档滚动偏移，改用 calc(100vw - 20px) 更稳。
