Vue 3 自定义 Hook 中异步数据的响应式导出与正确使用方式

本文详解 vue 3 组合式函数（composable）中异步初始化数据时如何保持响应性，解决 toRefs 导出后值仍为 undefined、watch 不触发等问题，并提供 Nuxt 3 兼容的可靠实现方案。

本文详解 vue 3 组合式函数（composable）中异步初始化数据时如何保持响应性，解决 `torefs` 导出后值仍为 `undefined`、`watch` 不触发等问题，并提供 nuxt 3 兼容的可靠实现方案。

在 Vue 3（尤其是 Nuxt 3）项目中，我们常通过自定义 composable 封装跨组件共享的异步逻辑，例如统一获取导航菜单。但若直接在 useNavigation() 中 await 请求并返回 toRefs(navs)，会遇到一个关键陷阱：该函数本身返回的是 promise，而非响应式对象。这导致组件中解构出的 main、footer 在初始化时为 undefined，且后续赋值无法触发响应式更新——因为 toRefs 是在 navs.main 还未被赋值（甚至尚未执行异步逻辑）时就被调用的。

根本原因在于：

• toRef(navs.main) 创建的是对 navs.main 当前值的响应式引用，但此时 navs.main 仍是初始值 false；
• 若 navs.main 后续被重新赋值（如 navs.main = menu.value），由于 toRef 指向的是原始属性而非响应式代理的深层追踪路径，其 ref 的 .value 不会自动同步更新（尤其当 navs 是 reactive 对象时，toRef(navs, ‘main’) 才能建立正确绑定）；
• 更重要的是，async function useNavigation() 返回的是 Promise，而 <script setup> 默认按同步方式解析顶层变量，导致解构行为发生在 Promise resolve 之前。</script>

✅ 正确解法：分离声明与初始化，确保响应式结构先行创建，异步逻辑延迟执行但不阻塞返回

以下是优化后的 composables/useNavigation.js 实现：

立即学习“前端免费学习笔记（深入）”；

// composables/useNavigation.js import { reactive, toRefs, computed } from 'vue'  // 共享响应式状态（单例，避免重复请求） const navs = reactive({   main: null,   // 初始设为 null 更语义化（区别于 false）   footer: null, })  export const useNavigation = () => {   const runTimeConfig = useRuntimeConfig()   const endpointMenus = `${runTimeConfig.public.API_URL}/wp-api-menus/v2/menus`    // 异步初始化逻辑（立即执行但不阻塞返回）   async function init() {     try {       const { data: menus, pending, error } = await useFetch(endpointMenus)        // 并行请求各菜单项（推荐使用 Promise.all 提升性能）       await Promise.all(         Object.keys(navs).map(async (key) => {           const menu = menus.value?.find((m) => m.slug === key)           if (!menu) return            const endpointMenu = `${runTimeConfig.public.API_URL}/wp-api-menus/v2/menus/${menu.ID}`           const { data: menuData } = await useFetch(endpointMenu)           navs[key] = menuData.value || []         })       )     } catch (err) {       console.error('[useNavigation] Failed to load menus:', err)     }   }    // 立即启动初始化（void 避免未处理 Promise 警告）   void init()    // ✅ 正确导出：toRefs 基于已存在的 reactive 对象，且使用 toRef(navs, key) 更健壮   return {     ...toRefs(navs),     // 如需派生 ref，优先用 computed 而非 toRef(navs.main)，确保响应式链完整     mainItems: computed(() => navs.main),     footerItems: computed(() => navs.footer),   } }

在组件中使用时，无需 async setup 或等待 Promise：

<!-- pages/[slug].vue --> <script setup> import { useNavigation } from '@/composables/useNavigation'  const { main, footer, mainItems } = useNavigation()  // ✅ 可直接 watch 响应式 ref（deep 可选，因 menu 数据通常为数组/对象） watch(main, (newVal) => {   console.log('Navigation main updated:', newVal) }, { immediate: true })  // ✅ computed 也能实时响应 const displayedMenu = computed(() => mainItems.value?.length > 0 ? mainItems.value : []) </script>  <template>   <nav v-if="main">     <ul>       <li v-for="item in main" :key="item.id">{{ item.title }}</li>     </ul>   </nav> </template>

⚠️ 关键注意事项：

• 不要在 composable 中 return await xxx()：这会使函数返回 Promise，破坏组合式 API 的响应式契约；
• 避免 toRef(navs.main) 写法：应使用 toRefs(navs) 或显式 toRef(navs, ‘main’)，确保 ref 与 reactive 对象属性建立正确绑定；
• Nuxt 3 环境下注意 SSR 兼容性：useFetch 在服务端执行，navs 单例状态不会跨请求共享（符合预期），但需确保 useNavigation() 在客户端也安全重入（当前实现已满足）；
• 性能优化建议：将多个 useFetch 合并为 Promise.all，减少网络往返；对菜单数据做缓存或防抖（如需频繁调用）；
• 错误处理不可省略：异步失败时应降级 ui（如显示空菜单）并记录日志，避免静默崩溃。

通过以上重构，main 和 footer 将作为真正的响应式 ref 被消费，watch 与 computed 均可正常工作，彻底解决“始终 undefined”和“监听失效”的核心问题。