Vue Router 文章详情页带锚点平滑滚动实现方法

如果你想在文章详情页中实现“带锚点的平滑滚动”，其实核心思路并不难：先启用 Vue Router 的 hash 模式，再为对应内容区块设置规范且唯一的 id；然后在 scrollBeha vior 中优先处理 to.hash，同时配置 beha vior: 'smooth' 与 offset 偏移；导航跳转部分则建议通过 完成。至于动态内容异步加载的情况，不建议一进入页面就立刻滚动，通常需要借助 setTimeout，或者在 onMounted 中监听 hash 后，再执行 scrollIntoView，这样锚点定位会更加稳定、准确。

在文章详情页中实现“带锚点的平滑滚动”，重点不仅是用户点击目录后页面能准确跳转到对应内容区域，更关键的是要让 URL 状态同步更新：既方便分享，也支持浏览器回退，并且整个跳转过程无需刷新页面。换句话说，这类需求不应只靠手动调用 scrollIntoView 临时处理，更推荐使用 Vue Router 的 scrollBeha vior 配置，结合清晰的 DOM 结构与适当的偏移修正，形成一套更稳定、更符合 SPA 场景的锚点滚动方案。

启用 hash 模式并规范锚点结构

首先要确保项目使用 Vue Router 的 hash 模式（通常默认就是如此），这样 URL 中的 #section-2 才能被正确识别为锚点目标。在文章详情页中，每个内容区块都应设置唯一且合法的 id，例如：

• 引言

• 常见问题

• 尽量避免使用空格、中文或特殊字符；更推荐采用小写字母加短横线的命名方式

配置 scrollBeha vior 处理锚点跳转

在 router 实例中定义 scrollBeha vior，并优先响应 URL 中的 hash 值，同时开启平滑滚动动画：

scrollBeha vior(to, from, sa vedPosition) {
if (to.hash) {
return {
el: to.hash,
beha vior: 'smooth',
// 若有固定头部，加偏移避免遮挡
offset: { y: 80 }
}
}
// 其他情况：返回时恢复位置，否则回到顶部
if (sa vedPosition) return sa vedPosition
return { top: 0 }
}

这里要注意：el: to.hash 会查找与当前 hash 对应的 id 元素；而 selector: to.hash 属于旧写法，在 Vue Router 4 中已统一改为 el。

导航链接要走标准路由跳转

无论是文章目录还是侧边栏导航，都建议使用 ，而不是原生 ，这样才能确保 Vue Router 正常接管跳转逻辑：

• ✅ 正确：常见问题
• ❌ 错误：常见问题（会绕过 router，无法触发 scrollBeha vior）
• 跳转完成后，URL 会显示为 /article/123#faq，结构更清晰，也便于复制链接直接分享

处理动态内容加载导致的滚动延迟

如果文章内容是通过 API 异步加载的，例如 markdown 渲染场景，那么 scrollBeha vior 可能会执行得过早——这时 DOM 还没有完全渲染出来。针对这种情况，可以增加适当延迟，或在内容渲染完成后再执行锚点滚动：

• 可以在 scrollBeha vior 中通过 setTimeout 延迟 200–300ms，确保目标元素已经挂载完成
• 更稳妥的方式是在组件 onMounted 中监听 router.currentRoute.value.hash，然后再调用 document.querySelector(hash)?.scrollIntoView()
• 不建议在 beforeRouteEnter 守卫中直接操作 DOM，因为此时组件实例尚未创建完成

整体来看，这套实现并不复杂，但细节很容易被忽略。只要把 hash 当作路由状态的一部分来处理，而不是单纯作为“页面视觉效果”的补充，就能让 Vue Router 在文章详情页中的锚点平滑滚动更稳定、更易维护，也更符合现代 SPA 应用的设计逻辑。