TanStack Vue Query 是 Vue 生态中用于管理、缓存和同步异步及远程数据的技能包，基于 @tanstack/vue-query 5.103.2 版本，配套 @tanstack/query-core 5.103.2。它重新导出了 query-core 的全部内容，因此 keepPreviousData、skipToken、focusManager、onlineManager、hydration 工具以及 observer 类都可以直接从 @tanstack/vue-query 导入。
用途 该技能面向需要在 Vue 中处理异步数据获取、缓存、同步与失效的场景。当代码中导入 "@tanstack/vue-query" 时即可使用。
主要能力 提供 useQuery、useMutation、useQueries、useInfiniteQuery 等组合式函数，以及 useQueryClient。支持查询键响应式追踪、缓存失效、乐观更新、SSR、多客户端、持久化缓存恢复等。
使用方式 安装插件：每个应用安装一次 VueQueryPlugin，它会创建或接受一个 QueryClient，并在应用范围内提供，同时负责挂载与卸载。可以传入自己的 queryClient（SSR 场景必需，每个请求一个全新客户端），或通过 queryClientConfig 让插件按默认配置构建。VueQueryPluginOptions 支持 queryClient 或 queryClientConfig（二选一）、queryClientKey（仅在安装多个客户端时使用）、clientPersister 与 clientPersisterOnSuccess（持久化缓存恢复）、enableDevtoolsV6Plugin。服务端不会挂载该客户端。useQueryClient(id?) 在注入上下文之外或未安装插件时会抛出错误。
基本查询示例：在 script setup 中导入 ref 与 useQuery，将 ref 直接放入 queryKey（无需 .value），在 queryFn 内读取 .value。返回的 status、data、error、refetch 等字段中，除 refetch、fetchNextPage、fetchPreviousPage、mutate、mutateAsync、reset 以及 suspense() 外，其余均为 Ref。useQueries 返回整个结果数组（或 combine 值）的单个 Ref，而非响应式数组。
基本变更示例：使用 useMutation 与 useQueryClient，在 onSuccess 中调用 queryClient.invalidateQueries 使查询失效。mutate 按设计会吞掉 rejection，每次调用的回调只对最新一次调用生效；如需每次调用返回 promise，应使用 mutateAsync。
需要留意的规则 查询键中不要解包 ref，应放入 ref 本身，并在 queryFn 内读取 .value。只有 queryKey 和 enabled 接受响应式 getter；其他位置传入函数即为真实回调（如 queryFn、select）。若要让任意选项响应式，可传入整体选项 getter：useQuery(() => ({ ... }))。initialData 不是响应式的，只读取一次。组合式函数应在 setup() 或 effectScope 中调用，作用域之外在开发模式下会警告内存泄漏。命令式获取应通过 queryClient.query() / queryClient.infiniteQuery()；fetchQuery、prefetchQuery、fetchInfiniteQuery、prefetchInfiniteQuery、ensureQueryData 已废弃并计划移除。共享查询建议用 queryOptions() 声明，使键携带数据类型，便于 getQueryData、invalidateQueries 与预取复用。
适用场景 适用于 Vue 应用中需要异步数据获取、缓存管理、数据同步、乐观更新、SSR 数据预取与缓存持久化的场景。
限制与环境 Vue 3 需 3.3+；Vue 2.6+ 需配合 @vue/composition-api（可选 peer），或使用 Vue 2.7 原生。采用 ESM 优先的双构建（build/modern、build/legacy），sideEffects: false。文档对应 v5，旧示例中可能出现 v4 API。
参考资料 references/api.md 列出每个导出、签名及源码位置；references/reactivity.md 涉及 refs、getters、skipToken、queryOptions getters、shallow；references/query-client.md 涉及 Vue QueryClient、响应式参数、失效时机、SSR、多客户端；references/mutations.md 涉及 mutations、mutationOptions、useMutationState、乐观更新；references/migration.md 涉及 v5 破坏性变更及 5.90 以来的版本规则。官方文档：https://tanstack.com/query/latest/docs/framework/vue/overview