本文由 Huifer 撰写,TanStack Ship 的独立开发者与维护者。我在多个 SaaS 产品中用 TanStack Query v5(原 React Query)交付过生产环境应用。这些指南来自一线生产经验——真实代码、实测行为,以及不回避的局限说明。
已核实的来源:tanstack.com、github.com/TanStack、web.dev、developers.mozilla.org。 最后更新:2026-10-23 · 更新日志
TanStack Query(原 React Query)v5 带来了明显的 API 改进和性能提升。在用它交付了数十个生产应用之后,下面这些是在规模化场景下真正跑得通的模式。
TL;DR: v5 是一个清理型版本。
cacheTime改名为gcTime,notifyOnChangeProps和isData被移除,useQuery也不再接受onError/onSuccess回调。按这个顺序迁移:包 →gcTime→notifyOnChangeProps→isData→ SSR hydration → 测试套件。之后再采用 v5 的惯用写法:query key factory、queryOptions()、有意图的staleTime、基于select的细粒度订阅,以及必定回滚的乐观更新。
TanStack Query v5 有哪些变化
v5 主要是一个清理与稳定化版本。v4 API 里有几条已经被标记废弃、团队打算在两个大版本内移除的路径,v5 就是这些移除真正落地的时候。
| 变更 | 旧版(v4) | 新版(v5) | 影响 |
|---|---|---|---|
| 缓存垃圾回收时间 | cacheTime | gcTime | 改名——cacheTime 在 v5 中已移除 |
| 重新渲染控制 | notifyOnChangeProps | select | 移除;select 是惯用替代方案 |
| 布尔数据快捷方式 | query.isData | query.isSuccess | 移除;改用明确的状态标志位 |
| 保留上一页数据 | keepPreviousData: true | placeholderData: keepPreviousData | 迁移到 placeholderData 选项 |
| 成功/错误回调 | useQuery 上的 onSuccess / onError | 无 | 使用 throwOnError + error boundary |
| Suspense | useQuery({ suspense: true }) | useSuspenseQuery | 拆成独立 hook |
**来源:**官方 migrating-to-v5 指南。
gcTime 改名
cacheTime 在 v4 里只是"软改名"为 gcTime。到 v5 它被彻底移除:
// v4(v4 中已废弃,v5 中移除)
const { data } = useQuery({
queryKey: ['todos'],
queryFn: fetchTodos,
cacheTime: 5 * 60 * 1000, // ❌ v5 中已移除
});
// v5
const { data } = useQuery({
queryKey: ['todos'],
queryFn: fetchTodos,
gcTime: 5 * 60 * 1000, // ✅ v5 中正确写法
});
notifyOnChangeProps 没了
这个用来指定"哪些结果属性变化才触发重新渲染"的选项被移除,取而代之的是通过 select 实现细粒度订阅:
// v4 —— notifyOnChangeProps(v5 中移除)
const { data } = useQuery({
queryKey: ['todos'],
queryFn: fetchTodos,
notifyOnChangeProps: ['data', 'error'], // ❌ 已移除
});
// v5 —— 改为订阅一个切片
const { data: todoCount } = useQuery({
queryKey: ['todos'],
queryFn: fetchTodos,
select: (data) => data.length, // ✅ 只有 length 变化时才重新渲染
});
select 在 v4 里也存在,但到了 v5,它成为官方支持的、避免无谓重新渲染的方式。
迁移检查清单
按顺序走完下面这些步骤——跳过任何一步,都可能把一次干净的迁移变成一场运行时 bug 排查。
- 升级包到
tanstack-query@5.x,并确认 React 的 peer dependency(v5 要求 React 18+)。 - 把所有
cacheTime换成gcTime(全项目搜索)。 - 把每个
notifyOnChangeProps改写成select;如果默认的重新渲染行为可以接受,也可以直接删掉。 - 把
isData换成isSuccess/isError/isLoading。 - 把
onSuccess/onError从useQuery上移走——它们现在属于useMutation;或者改用throwOnError配合 error boundary。 - 把
keepPreviousData: true换成placeholderData: keepPreviousData。 - 测试 SSR hydration——如果你用到了
dehydrate/HydrationBoundary。 - 跑一遍测试套件并认真看控制台——v5 会为每个被移除的 API 输出迁移警告。
分步迁移
第 1 步:升级包
npm install @tanstack/react-query@5
# 或者
pnpm add @tanstack/react-query@5
第 2 步:更新 QueryClient 默认值
// src/lib/queryClient.ts
import { QueryClient } from '@tanstack/react-query';
export const queryClient = new QueryClient({
defaultOptions: {
queries: {
gcTime: 1000 * 60 * 5, // 5 分钟(原来是 cacheTime)
staleTime: 1000 * 30, // 30 秒——一个合理的默认值
retry: 1,
refetchOnWindowFocus: true,
},
mutations: {
onError: (error) => {
console.error('Mutation error:', error);
},
},
},
});
第 3 步:采用 query key factory 模式
把 key 集中管理,是代码库规模超过几十个 query 之后仍能让缓存失效行为可预测的关键:
// src/lib/queryKeys.ts
export const queryKeys = {
users: {
all: ['users'] as const,
lists: () => [...queryKeys.users.all, 'list'] as const,
list: (filters: UserFilters) => [...queryKeys.users.lists(), filters] as const,
details: () => [...queryKeys.users.all, 'detail'] as const,
detail: (id: string) => [...queryKeys.users.details(), id] as const,
},
} as const;
同样的 factory 模式,配合按领域划分的 key 分组:
// 在组件中使用
const { data: users } = useQuery({
queryKey: queryKeys.users.list({ status: 'active' }),
queryFn: () => fetchUsers({ status: 'active' }),
});
第 4 步:用 select 实现细粒度响应
select 是 v5 订阅 query 数据某个切片的方式——组件不会因为与自己无关的变化而重新渲染:
// 这里只关心数量
const { data: userCount } = useQuery({
queryKey: queryKeys.users.all,
queryFn: fetchAllUsers,
select: (users) => users.length,
});
第 5 步:SSR hydration(如适用)
dehydrate 和 HydrationBoundary 的用法不变,v5 只是收紧了类型:
// app/page.tsx —— Next.js App Router 示例
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';
async function UsersPage() {
const queryClient = new QueryClient();
await queryClient.prefetchQuery({
queryKey: queryKeys.users.list({ status: 'active' }),
queryFn: () => fetchUsers({ status: 'active' }),
});
return (
<HydrationBoundary state={dehydrate(queryClient)}>
<UsersList />
</HydrationBoundary>
);
}
Query Key Factory
影响最大的一个模式:结构化的 query key factory。随手拼出来的字符串 key 会制造出微妙的 bug,并让缓存失效变得不可预测。
// queries/userKeys.ts
export const userKeys = {
all: ['users'] as const,
lists: () => [...userKeys.all, 'list'] as const,
list: (filters: UserFilters) => [...userKeys.lists(), filters] as const,
details: () => [...userKeys.all, 'detail'] as const,
detail: (id: string) => [...userKeys.details(), id] as const,
}
// 使用
const { data } = useQuery({
queryKey: userKeys.detail(userId),
queryFn: () => fetchUser(userId),
})
// 让所有 user 查询失效
queryClient.invalidateQueries({ queryKey: userKeys.all })
// 只让列表失效
queryClient.invalidateQueries({ queryKey: userKeys.lists() })
类型安全的 Query Options
v5 引入了 queryOptions(),用于编写可复用、类型安全的查询配置:
import { queryOptions } from '@tanstack/react-query'
export const userQueryOptions = (userId: string) =>
queryOptions({
queryKey: userKeys.detail(userId),
queryFn: () => fetchUser(userId),
staleTime: 5 * 60 * 1000, // 5 分钟
})
// 在组件中
const { data: user } = useQuery(userQueryOptions(userId))
// 在路由 loader 中(TanStack Router 集成)
export const Route = createFileRoute('/users/$userId')({
loader: ({ context, params }) =>
context.queryClient.ensureQueryData(userQueryOptions(params.userId)),
})
明确定义 Stale Time
别对所有数据都用默认的 staleTime: 0。先想清楚数据多久变一次:
// 用户偏好很少变化——缓存 1 小时
const { data: preferences } = useQuery({
queryKey: ['preferences'],
queryFn: fetchPreferences,
staleTime: 60 * 60 * 1000,
})
// 信息流数据持续变化——不做缓存
const { data: feed } = useQuery({
queryKey: ['feed'],
queryFn: fetchFeed,
staleTime: 0,
refetchInterval: 30_000,
})
// 产品目录——中等时长缓存
const { data: products } = useQuery({
queryKey: ['products', filters],
queryFn: () => fetchProducts(filters),
staleTime: 5 * 60 * 1000,
})
staleTime: Infinity 在 v5 里依然有效——它只是表示"永远不认为这份数据过期"。你可以把它用在按发布节奏变化的参考数据上;如果需要绝对保证,同时显式关掉自动重新获取的触发条件。
乐观更新
乐观更新让界面感觉是即时的。v5 让这件事干净了很多:
function useUpdateTodo() {
const queryClient = useQueryClient()
return useMutation({
mutationFn: updateTodo,
onMutate: async (updatedTodo) => {
// 取消进行中的查询,避免覆盖乐观更新的结果
await queryClient.cancelQueries({ queryKey: todoKeys.detail(updatedTodo.id) })
// 快照旧值,用于回滚
const previous = queryClient.getQueryData(todoKeys.detail(updatedTodo.id))
// 乐观更新
queryClient.setQueryData(todoKeys.detail(updatedTodo.id), (old) => ({
...old,
...updatedTodo,
}))
return { previous }
},
onError: (err, updatedTodo, context) => {
// 失败时回滚
queryClient.setQueryData(todoKeys.detail(updatedTodo.id), context?.previous)
},
onSettled: (data, error, updatedTodo) => {
// 变更结束后总是重新拉取
queryClient.invalidateQueries({ queryKey: todoKeys.detail(updatedTodo.id) })
},
})
}
onMutate → onError → onSettled 这三步就是完整的契约:onMutate 产出乐观状态并返回回滚所需的上下文,onError 用这份上下文还原,onSettled 总是让查询失效,好让下一次渲染反映服务端的真实数据。
基于游标的无限查询
对实时数据来说,基于游标的分页比 offset 分页更可靠:
const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
queryKey: ['posts', filters],
queryFn: ({ pageParam }) => fetchPosts({ cursor: pageParam, ...filters }),
initialPageParam: undefined as string | undefined,
getNextPageParam: (lastPage) => lastPage.nextCursor,
})
// 拍平各页数据用于渲染
const posts = data?.pages.flatMap((page) => page.items) ?? []
集成 Error Boundary
因为 v5 从 useQuery 中移除了 onError,那些"出错就应该打断路由"的错误改用 throwOnError 抛出,再由 boundary 捕获:
// 把错误抛给最近的 error boundary
const { data } = useQuery({
queryKey: ['critical-data'],
queryFn: fetchCriticalData,
throwOnError: true,
})
// 放在你的路由或组件树中
function RouteErrorBoundary({ error }: { error: Error }) {
return (
<div className="error-state">
<h2>Something went wrong</h2>
<p>{error.message}</p>
<button onClick={() => window.location.reload()}>Retry</button>
</div>
)
}
预取优化体验
鼠标悬停时预取数据,彻底消除加载态:
function PostCard({ post }: { post: Post }) {
const queryClient = useQueryClient()
return (
<Link
to="/posts/$postId"
params={{ postId: post.id }}
onMouseEnter={() => {
queryClient.prefetchQuery(postQueryOptions(post.id))
}}
>
{post.title}
</Link>
)
}
常见问题
TanStack Query v5 中最大的破坏性变更是哪些?
cacheTime → gcTime(旧名字已移除),notifyOnChangeProps 被移除、改用 select,isData 被移除、改用明确的状态标志位,以及 useQuery 不再接受 onSuccess / onError。
如何从 React Query v4 迁移到 v5?
先升级包,把所有 cacheTime 换成 gcTime,把 notifyOnChangeProps 的用法改写成 select,替换掉 isData 判断,然后每完成一步就跑一遍测试套件。官方迁移指南 列出了所有被移除的 API。
TanStack Query v5 能配合 Next.js App Router 使用吗?
可以。QueryClient 必须在客户端创建,以避免 hydration 不匹配;HydrationBoundary + dehydrate 的用法与 v4 相同。
staleTime: Infinity 仍然受支持吗?
支持——它在 v5 中没有被废弃。它的含义是数据永远不会被视为过期,因此如果你需要绝对保证,请配合显式的 refetchOnMount / refetchOnWindowFocus: false 一起使用。
v5 相比 v4 在性能上有哪些改进?
主要来自三方面:基于 select 的细粒度订阅(列表视图里重新渲染更少)、更清晰的 gcTime / staleTime 生命周期,以及更精细的查询取消行为。
延伸阅读: Tanstack Router 最佳实践 2026 · Tanstack Query 预订占位 · TanStack Query vs SWR
收尾
最重要的几点:
- Query key factory——从第一天起就结构化地组织 key
queryOptions()——在组件和 loader 之间共享查询配置- 有意图的 stale time——让缓存时长与数据变化频率匹配
- 乐观更新——永远处理好回滚,并在 settled 后重新拉取
- 悬停预取——你所能找到的最划算的性能提升
这些模式在生产环境中帮我省下了无数个排查数据过期和缓存失效 bug 的小时。先从 key factory 开始,再逐步推进。
DONE: content/i18n/zh/tanstack-query-v5-best-practices.md