Nuxt3页面过渡模式导致Swiper/Plyr插件初始化异常求助

问题描述 #

我在Nuxt3项目中用Composition API开发，页面集成了Swiper轮播和Plyr视频插件。未配置页面过渡或首次打开网站时功能一切正常；但在nuxt.config里设置pageTransition为out-in模式后，Swiper和Plyr只在首次加载时能正常初始化，页面切换时完全失效。

调试时发现：在onMounted钩子中通过nextTick后打印Swiper实例，能输出实例但组件根本没实际渲染初始化；只有当从这个页面跳转到其他页面时，之前的初始化操作才会执行，但此时页面已经要被销毁了。

把过渡模式改成in-out后，插件初始化恢复正常，但搞不懂具体原因，求解释和靠谱的解决方案。

相关代码 #

页面组件代码 #

<script setup>
const initSlider = async () => {
  await nextTick()

 setTimeout(()=> {
    slider.value = new Swiper(`#${id.value}`, {
      slidesPerView: 1,
      slidesPerGroup: 1,
      effect: 'fade',
      fadeEffect: {
        crossFade: true
      },
      modules: [EffectFade],
    })
  }, 400)
}

onMounted( () => {
  initSlider()
})
</script>

nuxt.config配置 #

export default defineNuxtConfig({
   app: {
      pageTransition: { name: 'page', mode: 'out-in' }
   }
})

过渡CSS #

.page-enter-active,
.page-leave-active {
   transition: opacity 5s;
}

.page-enter,
.page-leave-active {
   opacity: 0;
}

问题根源：out-in与in-out模式的执行逻辑差异 #

Nuxt的页面过渡完全遵循Vue过渡组件的规则：

• out-in模式：先执行旧页面的离开过渡，等旧页面完全消失（过渡100%完成），才开始新页面的进入过渡。
• in-out模式：先执行新页面的进入过渡，等新页面完全显示后，再处理旧页面的离开过渡。

你的问题就出在out-in的执行顺序上：

1. 页面切换时，旧页面的离开过渡要持续5秒（你的CSS设置了5秒的opacity过渡）。
2. 新页面的onMounted确实会触发，但此时旧页面还没完全卸载，新页面的DOM元素实际上处于“已创建但未真正挂载到文档流、不可见”的状态——因为out-in要等旧页面彻底走完过渡，才会让新页面真正显示。
3. 你用了400ms的setTimeout来初始化Swiper，这个时间远短于旧页面的5秒过渡时长，此时新页面的DOM还没被浏览器正确渲染，Swiper虽然能创建实例，但找不到可操作的有效DOM节点，自然无法正常初始化。
4. 当你跳转到其他页面时，之前的那个“未初始化成功”的页面变成了旧页面，它的离开过渡触发，此时它的DOM才被浏览器正确处理，Swiper的初始化代码才真正生效，但这时候页面已经要被销毁了，所以你会看到跳转时才执行初始化的诡异现象。

而in-out模式下，新页面的DOM会被立即挂载并渲染，onMounted+nextTick+setTimeout的组合刚好能赶上DOM就绪的时机，所以初始化成功。

解决方案：监听过渡完成事件，替代固定延迟 #

依赖setTimeout的固定延迟非常不可靠（比如改了过渡时长就失效），更稳妥的方式是监听Nuxt的页面过渡完成事件，确保在DOM完全就绪且过渡结束后再初始化插件。

方案1：用Nuxt的page:finish事件 #

在页面组件中监听页面过渡完成的全局事件，再执行初始化：

<script setup>
import { onMounted, onUnmounted, nextTick } from 'vue'

const initSlider = () => {
  slider.value = new Swiper(`#${id.value}`, {
    slidesPerView: 1,
    slidesPerGroup: 1,
    effect: 'fade',
    fadeEffect: {
      crossFade: true
    },
    modules: [EffectFade],
  })
}

const handlePageFinish = () => {
  nextTick(() => {
    initSlider()
  })
}

onMounted(() => {
  // 首次加载直接初始化
  initSlider()
  // 监听页面切换后的过渡完成事件
  window.addEventListener('page:finish', handlePageFinish)
})

onUnmounted(() => {
  // 销毁时移除监听，避免内存泄漏
  window.removeEventListener('page:finish', handlePageFinish)
})
</script>

方案2：监听过渡容器的transitionend事件 #

直接针对页面的过渡容器监听过渡结束事件：

<script setup>
import { onMounted, ref, nextTick } from 'vue'

const pageRef = ref(null)
const initSlider = () => {
  slider.value = new Swiper(`#${id.value}`, {
    slidesPerView: 1,
    slidesPerGroup: 1,
    effect: 'fade',
    fadeEffect: {
      crossFade: true
    },
    modules: [EffectFade],
  })
}

const handleTransitionEnd = (e) => {
  // 确保是opacity属性的过渡结束（避免其他过渡事件干扰）
  if (e.propertyName === 'opacity') {
    initSlider()
    pageRef.value.removeEventListener('transitionend', handleTransitionEnd)
  }
}

onMounted(() => {
  nextTick(() => {
    if (pageRef.value) {
      pageRef.value.addEventListener('transitionend', handleTransitionEnd)
    }
  })
})
</script>

<template>
  <div ref="pageRef">
    <!-- 页面内容，包括Swiper容器 -->
  </div>
</template>

方案3：保留out-in模式并调整初始化时机 #

如果你必须用out-in模式，可以去掉setTimeout，改用监听旧页面过渡完成后再初始化新页面插件。不过最推荐方案1，因为Nuxt的page:finish事件会准确触发在页面过渡完全结束之后，无需自己判断过渡状态。

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