Nuxt3路由跳转时onMounted钩子内无法找到DOM元素问题

云上老周

2026-8-29

问题根源

Nuxt 3 硬刷新和客户端路由跳转的DOM渲染时序存在本质差异，这是问题出现的核心原因：

整页硬刷新时，页面内容由服务端渲染完成后全量返回客户端，hydration流程结束后onMounted触发时，所有DOM节点已经完整插入文档流，全局选择器可以正常匹配到目标元素。
客户端路由跳转走SPA局部替换逻辑：如果页面配置了路由过渡、包含异步组件/v-if控制的节点、被<Suspense>包裹，onMounted触发时仅代表组件虚拟DOM完成挂载，不保证目标节点已经真实插入当前文档流；此时用document全局查询，上下文可能还停留在旧页面DOM树，要么匹配不到新页元素，要么误匹配到旧页残留的同名类节点，GSAP的ScrollTrigger初始化时拿不到有效trigger节点，就会抛出「Element not found」警告，动画逻辑直接终止。

另外你原有代码里duration: '3'传了字符串值，GSAP解析时容易出现异常，建议传数字类型，单位默认是秒。

修复方案

按以下顺序调整代码即可解决：

放弃全局类名选择器的DOM查询方式，改用Vue官方推荐的模板ref绑定目标元素，精准定位当前组件下的节点，不受路由切换、类名重复的影响。
GSAP初始化逻辑放到nextTick中执行，等待组件DOM全部完成渲染、插入文档流后再运行。
用GSAP的context能力批量管理动画实例，在组件卸载时统一回收ScrollTrigger和动画，避免路由切换后的内存泄漏和实例残留问题。
如果页面配置了路由过渡，可将初始化逻辑挪到页面的onAfterEnter过渡钩子中执行，确保过渡完成、DOM完全就绪后再初始化动画。

修改后的完整代码示例：

<template>
  <!-- 绑定模板ref到触发元素 -->
  <div class="introimage" ref="introImageTrigger">
    <img class="introimage__image" ref="introImageEl" src="your-image-path" />
  </div>
</template>

<script setup>
// 声明ref对应模板上的绑定
const introImageTrigger = ref(null)
const introImageEl = ref(null)
let gsapCtx = null

onMounted(() => {
  // 等待DOM更新插入完成
  nextTick(() => {
    // 兜底判断元素是否存在，避免极端场景下初始化报错
    if (!introImageTrigger.value || !introImageEl.value) return

    // 创建gsap上下文，方便后续批量清理
    gsapCtx = $gsap.context(() => {
      $gsap.to(introImageEl.value, {
        scrollTrigger: {
          trigger: introImageTrigger.value, // 直接传入DOM节点，不依赖选择器
          start: 'top 200px',
          end: '300%',
          scrub: true,
          reverse: true,
          markers: false,
          toggleActions: 'restart none none reverse',
        },
        height: 0,
        duration: 3, // 传数字类型，不要传字符串
      })
    })
  })
})

// 组件卸载时还原所有GSAP动画、清理ScrollTrigger实例
onUnmounted(() => {
  gsapCtx?.revert()
})
</script>

如果上述调整后路由跳转时仍偶发找不到元素，可以直接把GSAP初始化区域用<ClientOnly>组件包裹，强制该部分内容只在客户端完成渲染，彻底规避SSR hydration和时序问题。

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