Nuxt3中NuxtLink跳转锚点点击或刷新页面时不滚动问题

问题根源 #

• Nuxt3内置的路由滚动逻辑默认触发时机早于异步内容渲染完成：你的页面用useAsyncData拉取内容，滚动逻辑执行时目标锚点元素还未挂载到DOM，自然无法触发滚动
• 旧版vue-scrollTo长期未更新，未适配Nuxt3的Vite构建模式，才会抛出serialize is not defined报错，Nuxt3项目无需引入该依赖实现锚点滚动

方案一：修复全局滚动配置（一劳永逸，推荐） #

在项目根目录的nuxt.config.ts中补充正确的scrollBehavior配置，同时覆盖路由跳转、带hash刷新两种场景：

export default defineNuxtConfig({
  // 保留你原有的其他配置项
  app: {
    // 如果开启了页面过渡动画，不要删除你原有的过渡配置
    scrollBehavior(to, from, savedPosition) {
      // 优先返回浏览器记录的滚动位置
      if (savedPosition) return savedPosition
      // 处理锚点跳转
      if (to.hash) {
        return {
          el: to.hash,
          top: 20, // 偏移量，有固定顶部导航栏时改成导航栏高度即可，避免内容被遮挡
          behavior: 'smooth' // 开启平滑滚动
        }
      }
      // 普通页面跳转回到顶部
      return { top: 0 }
    }
  }
})

如果开启了页面过渡动画，上面的配置可能因为DOM在过渡过程中重建导致滚动失效，搭配下面的客户端插件兜底即可

方案二：客户端插件兜底（解决异步渲染、页面过渡导致的失效） #

在项目plugins目录下新建scroll.client.ts文件，该插件仅在客户端运行，会等页面全部异步内容挂载完成后再执行滚动逻辑，完美兼容带hash刷新页面的场景：

export default defineNuxtPlugin(() => {
  const router = useRouter()
  router.afterEach(() => {
    nextTick(() => {
      const hash = window.location.hash
      if (!hash) return
      const targetEl = document.querySelector(hash)
      if (!targetEl) return
      // 计算滚动位置，可自行调整偏移量
      const offset = 20
      const targetTop = targetEl.getBoundingClientRect().top + window.scrollY - offset
      window.scrollTo({
        top: targetTop,
        behavior: 'smooth'
      })
    })
  })
})

方案三：单链接快速实现（无需修改全局配置） #

如果只需要单个链接实现锚点跳转，直接给NuxtLink加点击事件用原生API实现即可，替换你原来的链接代码：

<nuxt-link 
  to="/" 
  @click.prevent="() => {
    const target = document.getElementById('projects')
    target?.scrollIntoView({ behavior: 'smooth', block: 'start' })
  }"
>
  Let's go
</nuxt-link>

注意：该方案仅能处理点击跳转场景，无法支持URL带hash刷新页面自动滚动的需求

避坑提示 #

• 无需在Nuxt3项目中安装vue-scrollTo依赖，原生API完全可以实现平滑滚动需求，还能避免构建报错
• 如果锚点区域包含异步加载的图片、组件，可在滚动逻辑前加短暂延迟等待资源加载，避免滚动位置计算偏差
• 存在固定顶部导航栏时，一定要在滚动偏移量中加上导航栏高度，避免锚点顶部的内容被导航遮挡

内容的提问来源于stack exchange，提问作者georgewoofbates