TanStack Query v5 迁移指南Vue 篇useQueries 响应式重构、Vue 3.3 版本要求与 injectionContext 支持【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query导读本文面向正在从 Vue Query v4 升级到 TanStack Query v5tanstack/vue-query的开发者完整讲解 v5 中与 Vue 框架强相关的三项破坏性变更useQueries返回值从reactive改为ref、Vue 3 最低版本提升至 v3.3、以及 composables 可在injectionContext中运行的新能力。读完本文你将理解这些变更背后的设计动机与底层原理并掌握对应的代码迁移方案与正确使用姿势。本文以 docs/framework/vue/guides/migrating-to-v5.md 为骨架并结合packages/vue-query包内的源码与测试进行纵深佐证关于各框架通用的破坏性变更单对象签名、cacheTime→gcTime等请参考 React 版迁移文档。Vue Query 专属破坏性变更概览在 TanStack Query v5 中除了所有框架共用的破坏性变更外tanstack/vue-query还额外包含三处只影响 Vue 生态的变更变更点影响范围迁移动作useQueries返回值从reactive变为ref使用useQueries并行查询的代码访问结果时改为.valueVue 3 最低版本要求 v3.3依赖 Vue 3 的项目升级vue依赖至^3.3.0composables 可在injectionContext中运行路由守卫、普通函数等非setup场景确保运行在effectScope内避免内存泄漏下面逐一深入。一、useQueries现在返回ref而不是reactive变更内容在 v5 中useQueriescomposable 返回的queries数组被包裹在ref中返回而不再是reactive对象。// v4 旧写法直接访问 queries[0].data const queries useQueries({ queries: [...] }) const firstData queries[0].data // v5 新写法先解包 .value const queries useQueries({ queries: [...] }) const firstData queries.value[0].data在模板中ref会被自动解包因此queries[0].data的模板用法不受影响但在script setup的 JS/TS 逻辑中必须显式访问.value。为什么 v4 的reactive实现有问题官方文档明确指出旧实现返回reactive数组带来了多个难以排查的问题展开返回值会丢失响应性reactive数组被展开spread后元素与原始代理之间的关联被切断用户容易在不知不觉中拿到一次性快照readonly包裹破坏 Vue 2 响应式检测v4 用readonly包裹返回值这在 Vue 2.6 中是静默失效的隐患到了 Vue 2.7 则直接表现为报错Vue 2 不支持将数组作为reactive的根值这是 Vue 2 响应式系统的固有限制。将返回值统一改为ref后上述问题全部得到修复同时让useQueries与useQuery、useMutation等其他 composables 保持一致——它们在 v5 中本就返回ref形态的字段见 useBaseQuery.ts 中toRefs(readonlyState)的处理方式。源码佐证返回值形态在 useQueries.ts 中内部状态由shallowRef承载const state shallowRef(getOptimisticResult()) // ... return options.shallow ? shallowReadonly(state) : (readonly(state) as ReadonlyRefTCombinedResult)函数签名也明确返回ReadonlyRefTCombinedResult见 useQueries.ts即一个只读的ref。此后观察器QueriesObserver的每次状态更新都会通过state.value getOptimisticResult()整体替换ref的内容见 useQueries.ts因此不需要像reactive那样对数组内部做深度代理。测试佐证.value访问模式仓库中的测试用例useQueries.test.ts全面采用了.value访问模式例如const queriesState useQueries({ queries }) expect(queriesState.value).toMatchObject([...]) // 访问结果必须先 .value queries.value.splice(queries.value.length, 0, ...) // 动态增删查询迁移建议全局搜索useQueries(的调用处将 JS 逻辑中对返回数组的直接索引访问改为queries.value[i]若你在 v4 中做过const list [...queries]这类展开操作v5 中请改为const list [...queries.value]或直接基于.value计算派生状态模板中v-foritem in queries无需改动ref自动解包。二、Vue 3 最低版本提升为 v3.3变更内容从 v5 开始若要使用 Vue 3最低版本必须为v3.3Vue 2.x 的支持要求保持不变仍然兼容 Vue 2.6 / 2.7。官方给出的理由是为了让后续新特性能够跟随 Vue 官方版本迭代tanstack/vue-query需要依赖 v3.3 引入的新 API例如hasInjectionContext这正是下一节injectionContext支持的基础设施。源码佐证peerDependencies 约束在 packages/vue-query/package.json 中peerDependencies 明确写为peerDependencies: { vue/composition-api: ^1.1.2, vue: ^2.6.0 || ^3.3.0 }这一声明意味着包管理器在安装tanstack/vue-query5时会校验 Vue 3 版本必须 3.3.0或使用 Vue 2.6。而仓库的 devDependencies 也同步使用vue: ^3.4.27见 package.json并在 CI 中通过vue-demi-switch分别对 Vue 2、Vue 2.7、Vue 3 三套环境跑测试test:lib脚本见 package.json确保三条兼容路径都经过验证。迁移建议若项目基于 Vue 3执行npm install vue^3.3或pnpm add vue^3.3完成升级若项目基于 Vue 2无需变更版本但请确保安装了可选的vue/composition-api依赖v5 中其 peer 范围仍为^1.1.2。三、新能力composables 可在injectionContext中运行变更背景v4 中vue-query的 composables 只能在组件的setup函数内运行。唯一的逃生通道是显式传入queryClient选项如useQuery(options, queryClient)从而跳过基于inject的查找。v5 引入了新能力只要调用方函数支持injectionContext即内部可以正常执行injectvue-querycomposables 就能脱离setup运行。典型场景是router navigation guards路由导航守卫import { useQueryClient } from tanstack/vue-query // 在路由守卫中直接使用 composable无需再手动传 queryClient router.beforeEach((to) { const queryClient useQueryClient() // 执行 prefetch、invalidate 等操作 })源码佐证useQueryClient 的上下文检测在 useQueryClient.ts 中v5 使用hasInjectionContext()Vue 3.3 新增 API来确保inject()可用export function useQueryClient(id ): QueryClient { // ensures that inject() can be used if (!hasInjectionContext()) { throw new Error( vue-query hooks can only be used inside setup() function or functions that support injection context., ) } const key getClientKey(id) const queryClient injectQueryClient(key) // ... }因此只要在路由守卫、服务函数等支持注入上下文的函数中调用useQueryClient就能拿到插件注入的客户端实例插件通过app.provide(clientKey, client)提供见 vueQueryPlugin.ts。重要警告必须在effectScope内运行否则可能内存泄漏虽然 composables 可以在injectionContext中运行了但官方特别强调使用这一新特性时请确保vue-querycomposable 运行在effectScope内否则可能导致内存泄漏。原因在于vue-query的 composable 内部大量依赖onScopeDispose来清理订阅例如 useBaseQuery.ts、useQueries.ts、useIsFetching.ts 都在作用域销毁时调用unsubscribe()释放 observer 订阅。如果 composable 运行在没有作用域的环境中这些清理回调永远不会被触发订阅就会一直存活形成内存泄漏。dev-only 警告为了帮助开发者尽早发现误用v5 在开发模式下加入了警告逻辑所有 composable 在入口处检查getCurrentScope()若返回为空即不在任何 effect scope 中则输出console.warn。该逻辑存在于 useBaseQuery.ts、useQueries.ts、useMutation.ts、useIsFetching.ts、useMutationState.ts、usePrefetchQuery.ts 等文件if (process.env.NODE_ENV development) { if (!getCurrentScope()) { console.warn( vue-query composable like useQuery() should only be used inside a setup() function or a running effect scope. They might otherwise lead to memory leaks., ) } }在非 setup 场景中的正确用法如果你确实需要在setup之外例如组合式函数、工具函数、路由守卫使用 composable推荐用effectScope显式包裹并在合适的生命周期中停止作用域import { effectScope, onScopeDispose } from vue import { useQuery } from tanstack/vue-query function useFeatureOutsideSetup() { const scope effectScope() const result scope.run(() { // 在这里调用 vue-query composable作用域会提供 onScopeDispose 能力 return useQuery({ queryKey: [feature], queryFn: fetchFeature }) }) // 在宿主销毁时停止作用域触发内部订阅清理 onScopeDispose(() scope.stop()) return result }若函数本身运行在组件setup内部则不需要额外处理——setup天然运行在组件的作用域中composable 内部的onScopeDispose会随组件卸载而执行。四、完整迁移检查清单针对 Vue 专属变更升级到 v5 时可按下述顺序自查升级依赖vue升至^3.3.0Vue 2 项目保持 2.6 并确认vue/composition-api存在升级tanstack/vue-query至 v5改造useQueries调用将 JS 逻辑中的数组访问补上.value删除任何基于reactive展开的依赖响应性的代码处理通用破坏性变更参考 React 版迁移文档 完成单对象签名、gcTime重命名、throwOnError重命名、remove方法移除等全局改动并可通过tanstack/query-codemods包的 v5remove-overloadscodemod 自动化处理大部分签名迁移packages/query-codemods内包含完整实现审查非setup用法如果在路由守卫等处调用了 composable确认这些调用点位于effectScope内开发模式下留意控制台的console.warn泄漏警告回归验证运行仓库为 vue-query 提供的测试命令pnpm run test:lib见 package.json该命令会分别在 Vue 2、Vue 2.7、Vue 3 三种环境下执行完整测试集确保三端行为一致。结语Vue Query v5 的三项 Vue 专属变更本质上都指向同一个目标让 composable 的响应式契约更简单、更一致、更可预测。useQueries统一返回ref消除了reactive在 Vue 2 上的兼容性隐患Vue 3.3 的版本门槛为新特性如hasInjectionContext铺平了道路而injectionContext支持则把vue-query的使用边界从组件setup拓展到了路由守卫等更广阔的场景。理解这三处变更背后的源码实现能帮助你在升级过程中快速定位问题并写出既符合新契约又不会泄漏内存的代码。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
TanStack Query v5 迁移指南Vue 篇useQueries 响应式重构、Vue 3.3 版本要求与 injectionContext 支持【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query导读本文面向正在从 Vue Query v4 升级到 TanStack Query v5tanstack/vue-query的开发者完整讲解 v5 中与 Vue 框架强相关的三项破坏性变更useQueries返回值从reactive改为ref、Vue 3 最低版本提升至 v3.3、以及 composables 可在injectionContext中运行的新能力。读完本文你将理解这些变更背后的设计动机与底层原理并掌握对应的代码迁移方案与正确使用姿势。本文以 docs/framework/vue/guides/migrating-to-v5.md 为骨架并结合packages/vue-query包内的源码与测试进行纵深佐证关于各框架通用的破坏性变更单对象签名、cacheTime→gcTime等请参考 React 版迁移文档。Vue Query 专属破坏性变更概览在 TanStack Query v5 中除了所有框架共用的破坏性变更外tanstack/vue-query还额外包含三处只影响 Vue 生态的变更变更点影响范围迁移动作useQueries返回值从reactive变为ref使用useQueries并行查询的代码访问结果时改为.valueVue 3 最低版本要求 v3.3依赖 Vue 3 的项目升级vue依赖至^3.3.0composables 可在injectionContext中运行路由守卫、普通函数等非setup场景确保运行在effectScope内避免内存泄漏下面逐一深入。一、useQueries现在返回ref而不是reactive变更内容在 v5 中useQueriescomposable 返回的queries数组被包裹在ref中返回而不再是reactive对象。// v4 旧写法直接访问 queries[0].data const queries useQueries({ queries: [...] }) const firstData queries[0].data // v5 新写法先解包 .value const queries useQueries({ queries: [...] }) const firstData queries.value[0].data在模板中ref会被自动解包因此queries[0].data的模板用法不受影响但在script setup的 JS/TS 逻辑中必须显式访问.value。为什么 v4 的reactive实现有问题官方文档明确指出旧实现返回reactive数组带来了多个难以排查的问题展开返回值会丢失响应性reactive数组被展开spread后元素与原始代理之间的关联被切断用户容易在不知不觉中拿到一次性快照readonly包裹破坏 Vue 2 响应式检测v4 用readonly包裹返回值这在 Vue 2.6 中是静默失效的隐患到了 Vue 2.7 则直接表现为报错Vue 2 不支持将数组作为reactive的根值这是 Vue 2 响应式系统的固有限制。将返回值统一改为ref后上述问题全部得到修复同时让useQueries与useQuery、useMutation等其他 composables 保持一致——它们在 v5 中本就返回ref形态的字段见 useBaseQuery.ts 中toRefs(readonlyState)的处理方式。源码佐证返回值形态在 useQueries.ts 中内部状态由shallowRef承载const state shallowRef(getOptimisticResult()) // ... return options.shallow ? shallowReadonly(state) : (readonly(state) as ReadonlyRefTCombinedResult)函数签名也明确返回ReadonlyRefTCombinedResult见 useQueries.ts即一个只读的ref。此后观察器QueriesObserver的每次状态更新都会通过state.value getOptimisticResult()整体替换ref的内容见 useQueries.ts因此不需要像reactive那样对数组内部做深度代理。测试佐证.value访问模式仓库中的测试用例useQueries.test.ts全面采用了.value访问模式例如const queriesState useQueries({ queries }) expect(queriesState.value).toMatchObject([...]) // 访问结果必须先 .value queries.value.splice(queries.value.length, 0, ...) // 动态增删查询迁移建议全局搜索useQueries(的调用处将 JS 逻辑中对返回数组的直接索引访问改为queries.value[i]若你在 v4 中做过const list [...queries]这类展开操作v5 中请改为const list [...queries.value]或直接基于.value计算派生状态模板中v-foritem in queries无需改动ref自动解包。二、Vue 3 最低版本提升为 v3.3变更内容从 v5 开始若要使用 Vue 3最低版本必须为v3.3Vue 2.x 的支持要求保持不变仍然兼容 Vue 2.6 / 2.7。官方给出的理由是为了让后续新特性能够跟随 Vue 官方版本迭代tanstack/vue-query需要依赖 v3.3 引入的新 API例如hasInjectionContext这正是下一节injectionContext支持的基础设施。源码佐证peerDependencies 约束在 packages/vue-query/package.json 中peerDependencies 明确写为peerDependencies: { vue/composition-api: ^1.1.2, vue: ^2.6.0 || ^3.3.0 }这一声明意味着包管理器在安装tanstack/vue-query5时会校验 Vue 3 版本必须 3.3.0或使用 Vue 2.6。而仓库的 devDependencies 也同步使用vue: ^3.4.27见 package.json并在 CI 中通过vue-demi-switch分别对 Vue 2、Vue 2.7、Vue 3 三套环境跑测试test:lib脚本见 package.json确保三条兼容路径都经过验证。迁移建议若项目基于 Vue 3执行npm install vue^3.3或pnpm add vue^3.3完成升级若项目基于 Vue 2无需变更版本但请确保安装了可选的vue/composition-api依赖v5 中其 peer 范围仍为^1.1.2。三、新能力composables 可在injectionContext中运行变更背景v4 中vue-query的 composables 只能在组件的setup函数内运行。唯一的逃生通道是显式传入queryClient选项如useQuery(options, queryClient)从而跳过基于inject的查找。v5 引入了新能力只要调用方函数支持injectionContext即内部可以正常执行injectvue-querycomposables 就能脱离setup运行。典型场景是router navigation guards路由导航守卫import { useQueryClient } from tanstack/vue-query // 在路由守卫中直接使用 composable无需再手动传 queryClient router.beforeEach((to) { const queryClient useQueryClient() // 执行 prefetch、invalidate 等操作 })源码佐证useQueryClient 的上下文检测在 useQueryClient.ts 中v5 使用hasInjectionContext()Vue 3.3 新增 API来确保inject()可用export function useQueryClient(id ): QueryClient { // ensures that inject() can be used if (!hasInjectionContext()) { throw new Error( vue-query hooks can only be used inside setup() function or functions that support injection context., ) } const key getClientKey(id) const queryClient injectQueryClient(key) // ... }因此只要在路由守卫、服务函数等支持注入上下文的函数中调用useQueryClient就能拿到插件注入的客户端实例插件通过app.provide(clientKey, client)提供见 vueQueryPlugin.ts。重要警告必须在effectScope内运行否则可能内存泄漏虽然 composables 可以在injectionContext中运行了但官方特别强调使用这一新特性时请确保vue-querycomposable 运行在effectScope内否则可能导致内存泄漏。原因在于vue-query的 composable 内部大量依赖onScopeDispose来清理订阅例如 useBaseQuery.ts、useQueries.ts、useIsFetching.ts 都在作用域销毁时调用unsubscribe()释放 observer 订阅。如果 composable 运行在没有作用域的环境中这些清理回调永远不会被触发订阅就会一直存活形成内存泄漏。dev-only 警告为了帮助开发者尽早发现误用v5 在开发模式下加入了警告逻辑所有 composable 在入口处检查getCurrentScope()若返回为空即不在任何 effect scope 中则输出console.warn。该逻辑存在于 useBaseQuery.ts、useQueries.ts、useMutation.ts、useIsFetching.ts、useMutationState.ts、usePrefetchQuery.ts 等文件if (process.env.NODE_ENV development) { if (!getCurrentScope()) { console.warn( vue-query composable like useQuery() should only be used inside a setup() function or a running effect scope. They might otherwise lead to memory leaks., ) } }在非 setup 场景中的正确用法如果你确实需要在setup之外例如组合式函数、工具函数、路由守卫使用 composable推荐用effectScope显式包裹并在合适的生命周期中停止作用域import { effectScope, onScopeDispose } from vue import { useQuery } from tanstack/vue-query function useFeatureOutsideSetup() { const scope effectScope() const result scope.run(() { // 在这里调用 vue-query composable作用域会提供 onScopeDispose 能力 return useQuery({ queryKey: [feature], queryFn: fetchFeature }) }) // 在宿主销毁时停止作用域触发内部订阅清理 onScopeDispose(() scope.stop()) return result }若函数本身运行在组件setup内部则不需要额外处理——setup天然运行在组件的作用域中composable 内部的onScopeDispose会随组件卸载而执行。四、完整迁移检查清单针对 Vue 专属变更升级到 v5 时可按下述顺序自查升级依赖vue升至^3.3.0Vue 2 项目保持 2.6 并确认vue/composition-api存在升级tanstack/vue-query至 v5改造useQueries调用将 JS 逻辑中的数组访问补上.value删除任何基于reactive展开的依赖响应性的代码处理通用破坏性变更参考 React 版迁移文档 完成单对象签名、gcTime重命名、throwOnError重命名、remove方法移除等全局改动并可通过tanstack/query-codemods包的 v5remove-overloadscodemod 自动化处理大部分签名迁移packages/query-codemods内包含完整实现审查非setup用法如果在路由守卫等处调用了 composable确认这些调用点位于effectScope内开发模式下留意控制台的console.warn泄漏警告回归验证运行仓库为 vue-query 提供的测试命令pnpm run test:lib见 package.json该命令会分别在 Vue 2、Vue 2.7、Vue 3 三种环境下执行完整测试集确保三端行为一致。结语Vue Query v5 的三项 Vue 专属变更本质上都指向同一个目标让 composable 的响应式契约更简单、更一致、更可预测。useQueries统一返回ref消除了reactive在 Vue 2 上的兼容性隐患Vue 3.3 的版本门槛为新特性如hasInjectionContext铺平了道路而injectionContext支持则把vue-query的使用边界从组件setup拓展到了路由守卫等更广阔的场景。理解这三处变更背后的源码实现能帮助你在升级过程中快速定位问题并写出既符合新契约又不会泄漏内存的代码。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
