TanStack Query v5 最佳实践:迁移指南与生产模式

零停机迁移到 TanStack Query v5。本文覆盖破坏性变更、新增 hooks、持久化查询,以及 React 开发者在生产环境中的落地模式与性能调优经验。

Huifer
Huifer
September 16, 202614 min read
其他语言:Deutsch · English

本文由 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)影响
缓存垃圾回收时间cacheTimegcTime改名——cacheTime 在 v5 中已移除
重新渲染控制notifyOnChangePropsselect移除;select 是惯用替代方案
布尔数据快捷方式query.isDataquery.isSuccess移除;改用明确的状态标志位
保留上一页数据keepPreviousData: trueplaceholderData: keepPreviousData迁移到 placeholderData 选项
成功/错误回调useQuery 上的 onSuccess / onError无使用 throwOnError + error boundary
SuspenseuseQuery({ suspense: true })useSuspenseQuery拆成独立 hook

**来源:**官方 migrating-to-v5 指南。

gcTime 改名

cacheTime 在 v4 里只是"软改名"为 gcTime。到 v5 它被彻底移除:

typescript
// 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 实现细粒度订阅:

typescript
// 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 步:升级包

bash
npm install @tanstack/react-query@5
# 或者
pnpm add @tanstack/react-query@5

第 2 步:更新 QueryClient 默认值

typescript
// 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 之后仍能让缓存失效行为可预测的关键:

ts
// 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 分组:

ts
// 在组件中使用
const { data: users } = useQuery({
  queryKey: queryKeys.users.list({ status: 'active' }),
  queryFn: () => fetchUsers({ status: 'active' }),
});

第 4 步:用 select 实现细粒度响应

select 是 v5 订阅 query 数据某个切片的方式——组件不会因为与自己无关的变化而重新渲染:

ts
// 这里只关心数量
const { data: userCount } = useQuery({
  queryKey: queryKeys.users.all,
  queryFn: fetchAllUsers,
  select: (users) => users.length,
});

第 5 步:SSR hydration(如适用)

dehydrate 和 HydrationBoundary 的用法不变,v5 只是收紧了类型:

tsx
// 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,并让缓存失效变得不可预测。

ts
// 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(),用于编写可复用、类型安全的查询配置:

ts
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。先想清楚数据多久变一次:

ts
// 用户偏好很少变化——缓存 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 让这件事干净了很多:

ts
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 分页更可靠:

ts
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 捕获:

tsx
// 把错误抛给最近的 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>
  )
}

预取优化体验

鼠标悬停时预取数据,彻底消除加载态:

tsx
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

收尾

最重要的几点:

  1. Query key factory——从第一天起就结构化地组织 key
  2. queryOptions()——在组件和 loader 之间共享查询配置
  3. 有意图的 stale time——让缓存时长与数据变化频率匹配
  4. 乐观更新——永远处理好回滚,并在 settled 后重新拉取
  5. 悬停预取——你所能找到的最划算的性能提升

这些模式在生产环境中帮我省下了无数个排查数据过期和缓存失效 bug 的小时。先从 key factory 开始,再逐步推进。

DONE: content/i18n/zh/tanstack-query-v5-best-practices.md

同主题的其他文章

本文覆盖其中一个角度;建议先看完整指南,也可浏览其他角度。