本文详解 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”和“监听失效”的核心问题。
