HTML锚点导航需确保id合法唯一、href与id严格匹配、h2/h3均处理并嵌套生成目录、启用scroll-behavior: smooth实现平滑滚动，任意环节脱节都会导致跳转失效。
HTML 文章锚点导航能做，但直接手写容易出错，尤其 id 不合法、大小写不一致、重复或缺失时，点击就失效。核心不是“能不能”，而是“怎么让每个环节都稳”。
id 必须合法且全局唯一，否则 href="#xxx" 白写
浏览器只认合法 id 做锚点目标，不是随便起个名字就行。常见翻车点：
-
id含空格、中文、标点（如id="用户登录"或id="1.简介"）→ 跳转失败或跳到第一个匹配项 -
id以数字开头（如id="2-intro"）→ 部分老浏览器不识别 - 多个标题用了同一个
id="section"→ 只命中第一个，其余链接全失效 - 标题没写
id，又没用 JS 补 →href="#undefined"，点不动
生成规则建议统一用脚本处理：toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')，例如 “API 错误处理（v2）” → api-error-handling-v2。
h2 和 h3 都要抓，不能只选一级标题
文章目录需要体现层级结构，“章-节”关系缺一不可。只用 document.querySelectorAll('h2') 会漏掉所有小节；只抓 h3 又没主干。
立即学习“前端免费学习笔记（深入）”；
- 必须一次性获取：
document.querySelectorAll('h2, h3') - 遍历时判断
el.tagName === 'H2'还是'H3'，决定生成<li>还是嵌套的<ul> - 每个元素都要检查
el.id，为空就按规则自动生成，别跳过 - 插入目录用
toc.innerHTML = htmlString，避免循环appendChild触发多次重排
href 和 id 必须严格一致，大小写、连字符、空格都不能差
这是最常被忽略的细节。哪怕你生成了 id="user-login-flow"，链接写成 href="#User-Login-Flow" 或 href="#user_login_flow"，都会断链。
- 链接里的
href值必须是"#" + el.id，直接取值，别手拼 - 如果 JS 里用了
el.textContent.toLowerCase()生成id，那链接也得用同一套逻辑，别一个转小写一个没转 - 调试时右键检查链接，看
href是不是你预期的；再检查目标元素是否真有那个id，且没被其他脚本覆盖
scroll-behavior: smooth 不是默认行为，得手动开
原生锚点跳转是瞬间滚动，长页面下用户容易迷失。这不是 bug，是浏览器默认策略。
- 加在
<html>或<body>上即可：scroll-behavior: smooth - CSS 写法最轻量：
html { scroll-behavior: smooth; } - 不用 JS 就能生效，但注意 Safari 旧版本需加前缀或降级用 JS 滚动
- 动态内容（如 Markdown 渲染后插入的标题）若没提前生成
id，smooth 也救不了跳转失败
真正难的不是写几行 HTML，而是让 id 生成、链接生成、DOM 插入、CSS 行为这四步全程咬合。任意一环脱节，用户点下去就是静音——没报错，也不动。
