id命名须避开数字开头和特殊字符，推荐小写字母+连字符+数字组合；动态插入后锚点不滚动需用MutationObserver监听元素挂载；scroll-behavior: smooth必须写在html上；固定导航栏遮挡应使用scroll-margin-top修正。
id命名必须避开数字开头和特殊字符
动态生成的 id 若以数字开头（如 id="1-section"），在 Safari 旧版本或部分解析器中会静默失效——浏览器可能根本找不到该元素，导致锚点跳转无声失败。中文、空格、点号（.）、括号等也属于非法字符，id="联系我们" 或 id="demo.1" 都会让 document.querySelector("#demo.1") 返回 null。
推荐策略是统一用小写字母 + 连字符 + 数字组合，例如：id="section-api-reference-2"。自动化脚本生成时，可用正则清洗原始标题：title.replace(/[^a-z0-9-]/g, '-').replace(/^-+|-+$/g, '').replace(/-{2,}/g, '-') ，再确保不以数字起始（前缀加 s-）。
动态插入后锚点不滚动？别等 DOMContentLoaded
测试页面常通过 JS 插入代码块、运行结果或折叠面板，此时原生锚点跳转（靠 URL hash 触发）往往在 DOM 渲染前就执行完毕，目标 id 还不存在，滚动自然失效。
不能只监听 DOMContentLoaded 或 window.load，而应监听目标元素是否真正挂载：
立即学习“前端免费学习笔记（深入）”；
- 用
MutationObserver监听document.body的childList和subtree - 一旦
document.querySelector(location.hash)返回有效节点，立即调用el.scrollIntoView({ behavior: 'smooth', block: 'start' }) - 成功后立刻
observer.disconnect()，避免重复触发
scroll-behavior: smooth 写在 html 上才生效
很多团队把 scroll-behavior: smooth 写在 body 或全局选择器 * 上，结果平滑滚动始终不触发——因为该属性只对「滚动上下文根」起作用，现代浏览器的主滚动容器是 html 元素，不是 body。
验证方式：打开开发者工具 → 选中 标签 → 查看 computed 样式中 scroll-behavior 是否为 smooth，且未被 !important 覆盖（某些 UI 框架如 Ant Design 会强制设为 auto !important，需显式覆盖）。
固定导航栏遮挡目标？用 scroll-margin-top 修正，不是 margin-top
点击锚点后内容被吸顶 header 盖住，不是“没滚到位”，而是浏览器默认把目标元素顶部对齐视口顶部。此时改 margin-top 或 padding-top 会破坏布局流，且无法保证所有设备一致。
正确做法是给目标元素本身加 scroll-margin-top：
-
h2[id], .section[id] { scroll-margin-top: 64px; }（数值等于固定头部高度） - 支持响应式：用媒体查询适配移动端更矮的 header
- 注意：该属性只在目标元素处于可滚动上下文内生效；若目标在 Shadow DOM 或 iframe 中，需单独设置
动态生成的锚点元素，建议在插入 DOM 后统一加上该 CSS 类或内联 style，避免漏掉。
