Nuxt.js中vue-text-transition组件不生效如何排查解决

• 在Nuxt.js项目中使用vue-text-transition组件时，组件迁移后无法正常运行，相同实现逻辑在纯Vue项目中可正常工作
• 项目采用组合式API开发，通过const showTitle = ref(false)定义控制文本显隐的响应式变量，初步怀疑异常由响应式失效导致

该问题和ref响应式本身无关，核心原因是vue-text-transition是纯客户端组件，内部依赖浏览器DOM/BOM API，而Nuxt.js默认开启SSR服务端渲染模式，服务端预渲染阶段组件无法获取DOM实例，同时如果组件注册/加载时未做客户端侧隔离，会触发hydration注水不匹配，最终导致组件交互、动画效果完全失效。

• 按需加载时做客户端隔离
  在单文件组件中使用异步组件方式引入vue-text-transition，同时用Nuxt内置的ClientOnly组件包裹组件实例，确保组件仅在客户端侧渲染：

  <template>
    <ClientOnly>
      <VueTextTransition>
        <!-- 业务文本内容 -->
      </VueTextTransition>
    </ClientOnly>
  </template>
  
  <script setup>
  const VueTextTransition = defineAsyncComponent(() => import('vue-text-transition'))
  const showTitle = ref(false)
  // 注意：script逻辑中修改ref值必须操作.value属性，错误赋值会导致响应式丢失
  // 正确赋值示例：showTitle.value = true
  </script>
  

• 全局注册时指定客户端插件
  如果需要全局注册组件，在Nuxt的plugins目录下创建带.client后缀的插件文件，Nuxt会自动识别该插件仅在客户端侧加载：

  // plugins/vue-text-transition.client.ts
  import VueTextTransition from 'vue-text-transition'
  export default defineNuxtPlugin((nuxtApp) => {
    nuxtApp.vueApp.component('VueTextTransition', VueTextTransition)
  })
  

校验提示：修复后可清空浏览器缓存重启项目，检查控制台是否存在hydration相关报错，无报错即代表渲染链路正常。

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