<p>✅ 正确写法是 html { scroll-behavior: smooth; }，必须作用于 html 元素（主滚动容器），写在 body 或 * 上无效；需确保 href 与 id 严格匹配、目标元素存在且可见，并用 scroll-margin-top 解决固定导航栏遮挡。</p>
直接加 html { scroll-behavior: smooth; } 就能实现平滑定位，但 90% 的“不生效”问题出在 CSS 位置写错、id 不合法或目标不可见，不是 JS 没写对。
scroll-behavior: smooth 必须写在 html 元素上
这个属性只对「滚动上下文根」起作用。现代浏览器的主滚动容器是 html 元素，不是 body —— 即使你看到 body 在动，它也只是视觉代理。
- ✅ 正确：
html { scroll-behavior: smooth; }，放在全局样式最前面 - ❌ 无效：
body { scroll-behavior: smooth; }、* { scroll-behavior: smooth; }、.wrapper { scroll-behavior: smooth; }（除非它是局部滚动容器） - 检查方式：开发者工具中选中
html元素 → 查看 computed 样式里scroll-behavior是否为smooth，且未被!important覆盖 - 某些 UI 框架（如 Ant Design）会重置为
auto !important，需手动覆盖
href 和 id 必须严格匹配且合法
锚点跳转是原生行为，不报错也不警告，错一点就静默失败。
-
href必须是#section-1这种格式，不能是section-1、/#section-1或?id=section-1 -
id值不能以数字开头（如id="1-section"在旧版 Safari 可能失效），推荐用id="section-1" -
id中不能含空格、中文或特殊符号（id="联系我们"或id="contact us"都会中断） - 同一页面内
id必须唯一；重复时只滚动到第一个匹配元素 -
id必须存在于当前 DOM 中——Vue/React 动态渲染的内容，点击时若还没挂载，getElementById返回null，跳转即失效
固定头部遮挡时，用 scroll-margin-top 补偿
默认滚动会把目标元素顶部贴到视口顶部，但 position: fixed 导航栏会盖住内容。别用负 margin 或 padding 挤开目标元素——这破坏布局，且不解决定位逻辑。
立即学习“前端免费学习笔记（深入）”；
- 正确做法：给目标元素加
scroll-margin-top，例如：h2[id] { scroll-margin-top: 64px; } - 该值应等于固定头部高度（含 border/padding），支持
px、rem、vh等单位 - 注意：此属性只在目标元素处于可滚动上下文内才生效；若目标在 Shadow DOM 或 iframe 中，需单独设置
- 不要写成
margin-top或padding-top，它们影响的是布局流，不是滚动锚点偏移
动态内容加载后锚点跳转偏移怎么办
懒加载章节、AJAX 插入区块、或 Vue/React 异步组件渲染后，目标元素的实际 offsetTop 会变，但浏览器按旧 DOM 快照滚动，结果停在错误位置。
- 禁用原生跳转行为：
e.preventDefault()，避免href="#id"直接触发瞬移 - 先查目标是否存在：
const el = document.getElementById(id)，不存在就等一帧：requestAnimationFrame(() => scrollToTarget(id)) - 若目标属于尚未加载的模块，得监听对应加载完成事件（比如自定义
custom-load事件） - 用
el.scrollIntoView({ behavior: 'smooth' })时，必须确保el已渲染且可见；Safari ≤15.3 和部分安卓 WebView 不支持behavior: 'smooth'，可用'scrollBehavior' in document.documentElement.style检测后降级
最易被忽略的是：scroll-margin-top 是作用在目标元素上的，不是导航栏；而 scroll-behavior 是作用在滚动容器上的，不是随便哪个父元素都行——这两个位置一旦写反，效果就彻底消失，且控制台毫无提示。
