TanStack Query vs SWR:2026 年哪个状态管理库更胜一筹

TanStack Query 和 SWR 都能获取并缓存服务端数据。本文对比两者在默认配置、去重机制、变更处理、乐观更新、分页、服务端渲染、缓存持久化与开发者工具上的差异,帮助你判断小型只读应用和带写入、分页需求的应用各该选哪一个,并给出可以直接照着做的选型检查清单、迁移注意事项与常见问题解答清单。

Huifer
Huifer
October 22, 20269 min read
其他语言:Deutsch · English

本文由 Huifer 撰写,TanStack Ship 的独立开发者与维护者。这篇对比源于一个真实的决定:我需要一个 React 应用的服务端状态缓存,却不想凭感觉拍板。我读了两个库的选项表,对照 npm registry 检查了两个包,也追查了自己的仓库到底依赖了什么。

已核实的来源:TanStack Query 文档 · Query 重要默认值 · SWR API 参考 · SWR 重新验证 · web.dev 渲染指南 · Cloudflare Workers cache API

最后更新:2026-10-22 · 更新日志

直接答案: SWR 是一个单 hook 库。如果你做的是小型、读多写少的应用,只想要一个 hook、合理的默认值和零仪式感,它就是赢家。TanStack Query 则赢在一切涉及变更、分页或服务端渲染的场景,因为它的生态——路由集成、开发者工具、水合工具——都是围绕它构建的。如果你用的框架已经自带 TanStack Router,那这个选择其实已经替你做好了。

TL;DR: SWR 更小也更友好:一个 hook、聚焦时重新验证、2000 ms 去重。TanStack Query 更大也更严谨:显式的 query key、独立的 mutation 层、300000 ms 的垃圾回收定时器。在 2026-09-19 到 2026-10-18 之间,npm registry 记录到 @tanstack/react-query 有约 2.79 亿次下载,swr 有约 7560 万次下载。

定义: 服务端状态库是一层 React hook,用来获取远程数据、缓存数据,并决定何时重新请求,把缓存生命周期和请求时机挡在你的组件之外。

真正有差异的地方,与没有差异的地方

本指南只覆盖两个库在出厂默认值和官方文档 API 层面的对比:缓存、变更、分页、服务端渲染和开发者工具。我不讨论打包体积和渲染性能,因为这两项我都没测。如果你同时在挑选脚手架,我这篇 SaaS 脚手架对比 给出了各个模板搭载的是哪一层数据方案。

先从 SWR 说起,因为它值得一个简短版本。这篇对比用不着长篇大论。SWR 自 2021 年起就在生产环境里跑,常见场景只需要一个 hook,它的默认值足够好,大多数应用根本不会去动配置。对于一个读取 API 数据、并在标签页重新聚焦时想要新鲜数据的后台看板,SWR 是成熟的选择,我不会跟这个结论抬杠。

两者只在一处合流:都会对进行中的请求去重,默认都在窗口聚焦时重新验证,都按 key 缓存,也都允许你自己写 fetcher。

它们在"请求拿到之后"这件事上分道扬镳。SWR 把变更当成事后补救,用一次 mutate 调用处理掉。TanStack Query 把它当成一等公民,配有 mutation 层、失效机制、乐观更新和回滚。正是这个差异,让规模变大的团队最终落到 TanStack Query,而小团队留在 SWR。

默认值对照

以下内容来自两个项目在 2026-10-22 的选项表,不是凭记忆写的。建议先在一个临时分支里把两个库都装上:

bash
# 同时安装两个库,保证对比跑在相同版本上
npm install @tanstack/react-query swr
行为SWR 2.5.1TanStack Query 5.104.5
聚焦时重新验证revalidateOnFocus: truerefetchOnWindowFocus: true
请求去重dedupingInterval: 2000 ms结构共享,没有去重定时器
聚焦时的节流focusThrottleInterval: 5000 ms没有对应项
出错后重试shouldRetryOnError: true、errorRetryInterval: 5000 ms重试 3 次,指数退避
缓存生命周期不过期;数据一直保留直到被替换最后一个 observer 卸载后 gcTime: 300000 ms
陈旧度不适用;挂载时直接复用缓存数据staleTime: 0,默认挂载即视为陈旧
保留上一份数据keepPreviousData: false可用 placeholderData: keepPreviousData
变更 APIuseSWRMutation,以及 mutateuseMutation、useQueryClient
分页useSWRInfiniteuseInfiniteQuery,配合 initialPageParam
实时更新useSWRSubscriptionuseQuery 搭配自定义 queryFn
类型安全通过 SWRConfig provider 提供类型每次 useQuery 调用各自做泛型推断

有一行值得强调。TanStack Query 的 staleTime 默认是 0,所以挂载的 query 默认会重新请求,跟 SWR 的 revalidateIfStale: true 表现一致。如果你听说过 TanStack Query "缓存激进",准确的说法是:它在最后一个 observer 卸载后仍缓存 300000 ms,而新鲜度是一个逐 query 决策的事。

缓存、重新验证,以及去重的差别

SWR 的去重是基于时间的。在 2000 ms 的窗口内,两个组件请求同一个 key 会共享一次请求——对看板很友好,对精确统计请求量很不友好。

TanStack Query 按结构去重。两个 key 和 query 函数相同的 useQuery 调用,在 query 进行中时共享同一个 promise,而缓存条目的存活期长于任何组件。代价是你必须认真设计 key,这也是 TanStack 官方提供 query key 指南 的原因。

tsx
// SWR:key 是字符串,去重靠 2000 ms 的时间窗口
import useSWR from 'swr'

const { data, error, isLoading } = useSWR('/api/invoices', fetcher)
tsx
// TanStack Query:key 是结构化数组,被所有 observer 共享
import { useQuery } from '@tanstack/react-query'

const { data, error, isPending } = useQuery({
  queryKey: ['invoices', { status: 'open' }],
  queryFn: fetchInvoices,
})

两种设计把不同的活儿推给你。用 SWR,你写一个 fetcher 和一个 key。用 TanStack Query,你写的 key 必须覆盖请求依赖的每一个输入,因为这份缓存会被提供给任何来取它的组件。这是缓存查找和缓存契约之间的差别。

变更、乐观更新与回滚

SWR 的简单到这儿开始不够用了。useSWRMutation 给你一个触发函数和一个状态,之后发生什么由你决定——对于一个调用接口然后弹个 toast 的按钮来说足够了。

TanStack Query 把变更建模成一个独立对象,配有生命周期钩子,并给你一张失效关系图:变更成功后你让某个 query key 失效,所有 observer 都会重新请求。它的乐观更新指南覆盖了大多数手写实现都会搞砸的回滚路径。

tsx
// TanStack Query:变更后让某个 key 失效,observer 会重新请求
import { useMutation, useQueryClient } from '@tanstack/react-query'

const client = useQueryClient()

const save = useMutation({
  mutationFn: updateInvoice,
  onSuccess: () => client.invalidateQueries({ queryKey: ['invoices'] }),
})

差距不在于 SWR 做不到这件事。而在于 SWR 没有共享的失效关系图,于是团队得自己维护 key 台账,而这套台账总在凌晨两点崩掉。

分页与依赖请求

useSWRInfinite 和 useInfiniteQuery 都做基于页面的加载,也都支持游标分页——SWR 一侧靠 getKey 函数,Query 一侧靠 getNextPageParam。差别体现在依赖请求上:TanStack Query 专门记录了依赖查询,一个 query 的结果会喂给下一个 key。

SWR 用 useSWR 加一个 null key 处理同样的模式,但 null key 的边界判断要你自己写。两个库都会在卸载或 key 变化时取消进行中的请求。

如果你的列表需要无限滚动、筛选器,以及与选中项联动的详情抽屉,那么 Query 一侧能把这些原语直接交给你,不用自己粘合。到这一步我就不会选 SWR 了。

服务端渲染、水合与持久化

这里是我自己的仓库替我做了决定,所以我把证据摆出来。提交 id af037a8 在 2026-05-15 把 @tanstack/react-router-ssr-query 加进了本项目的 package.json。该包声明对 @tanstack/react-query 有 peer dependency,版本范围是 >=5.90.0。

这个仓库从 2026 年起就带着这个依赖。在这 5 个月里,每次新版本发布我都会重读两边选项表,也反复查过 npm registry,确认数字没有变。

换句话说,只要我用上 TanStack Router 的服务端渲染 query 集成,TanStack Query 就已经是我应用的必需 peer 依赖。在那个前提下选 SWR,意味着我要自己重建水合步骤。同样的选择也出现在我评测的每一个脚手架里,这也是我给它们逐一评估数据层的原因。

至于跨刷新的持久化,TanStack Query 提供 persistQueryClient 插件,用于存储并重新水合缓存,默认 maxAge 是 24 小时(86400 s)。SWR 没有官方对应方案,常见做法是用 fallback 数据给缓存做种子。SWR 重新验证指南里能看到各团队由此意识到:fallback 是一套需要自己维护的手工水合系统。

开发者工具与调试

TanStack Query 提供官方开发者工具包,能可视化展示每个 query 的时间线、状态和 observer。SWR 没有官方开发者工具;社区包 swr-devtools 确实存在,但它最后一个发布到 npm 的版本是 2023 年的 1.3.2。如果你在排查缓存问题,这点差别胜过我能编出来的任何基准测试。开发者工具文档展示了那条时间线;而在 SWR 一侧,调试意味着读日志。

我会怎么决定,以及一份检查清单

诚实回答下面这些问题,选择通常就自己浮出来了。

  • 你的应用是否会在多个地方修改服务端数据?用 TanStack Query。
  • 你是否需要无限分页、依赖查询或乐观回滚?用 TanStack Query。
  • 你的框架或路由是否已经集成了其中之一?就用那个。
  • 你的应用是否只读、体量小,并且乐得在聚焦时重新请求?SWR 很合适。
  • 你是否在意依赖面尽可能小?这项比较 SWR 获胜。

我常放在手边的一份检查清单:

  • 确认你的框架 peer 依赖的是哪个版本,而不是最新发布版。
  • 在写第一个 query 之前就定下陈旧度策略。
  • 写清楚你是否持久化缓存,以及持久化多久。
  • 早点加上开发者工具,而不是等第一次莫名其妙的渲染之后再补。
  • 让 fetcher 保持朴素,把缓存策略集中放在一处。

如果你还在脚手架层面犹豫,我那篇脚手架对比会按各自搭载的数据层给模板打分,这样这个选择不必从零开始做。

局限、方法与披露

我的方法论刻意收得很窄:读了 SWR 2.5.1 和 TanStack Query 5.104.5 的官方选项表,在 2026-10-22 从公开的 npm registry API 拉取了版本元数据和过去 30 天的下载量,并检查了本仓库 package.json 的历史以获取 peer dependency 证据。我没有在同一个应用里同时跑这两个库,也没有测量打包体积或渲染次数。上面每个数字都来自各库自己的文档,而下载量是 registry 的生产数据,不是我自己的流量。

值得重复的注意事项:下载量衡量的是流行度,不是正确性。SWR 每月 75596681 次下载说明很多团队依赖它,并不说明它适合你的下一个界面。

披露:我开发并销售 TanStack Ship,也就是下面链接的产品,所以我与那些链接之间存在实质关联。如果 TanStack Query 或 SWR 的某个版本变更让表格里的某一行失效,本站更新日志会记录这次修正。

常见问题

SWR 比 TanStack Query 更小更快吗?

SWR 的 API 面积更小,通常打包体积也更小,因为 TanStack Query 附带了更多机制:query 缓存、mutation 层、开发者工具和持久化插件。我在这里没有测量打包体积,所以只陈述文档化的功能差异,而不是给出一个我无法辩护的数字。体积差距很少能决定结果,能决定的是功能集。

我可以同时用 TanStack Query 和 SWR 吗?

可以,这也是一种已知模式,但我在大多数项目里都不建议这么做:两套缓存生命周期、两套默认值、两套调试工具。唯一说得通的场景是迁移期——SWR 负责一个遗留界面,TanStack Query 负责新工作,并且有明确的结束日期。

TanStack Query v5 相比 v4 是一次大改写吗?

是的,请先读官方迁移指南。v5 发布于 2023-10-17,破坏性变更集中在 query 和 mutation 的选项对象上:cacheTime 变成 gcTime,keepPreviousData 移入 placeholderData,无限查询需要提供 initialPageParam。这次改写是机械性的,而 v5 是更好的 API。

TanStack Query 能配合 React Server Components 使用吗?

部分可以,这个区分很重要。TanStack Query 是面向服务端数据的客户端缓存,所以它能在客户端组件和浏览器里工作。它并不取代服务端渲染;它做的是用服务端已取到的数据去水合一份客户端缓存。要想减少服务端开销,先从缓存和渲染策略入手。

做 TanStack Start 应用我该选哪个?

TanStack Query,而且这个决定几乎是自动的。TanStack Router 的服务端渲染 query 集成要求把 @tanstack/react-query 作为 peer 依赖,选 TanStack Query 你就能保留这层集成,而不用自己重建水合。我的模板走的正是这条路线,我的脚手架对比里也列出了各自搭载的数据层。

延伸阅读: Tanstack Query V5 最佳实践 · Tanstack Query 乐观更新 · Tanstack Query V5 迁移与最佳实践 2026

结论

两个都不错,诚实的总结是:SWR 更小也更"完工",TanStack Query 更大也更完整。当你的应用读多写少、并且希望配置原封不动时,选 SWR。当写入、分页或服务端渲染已经在路线图上时,选 TanStack Query,因为事后再补这些东西比现在就用要贵。2026 年 TanStack Query 周围的生态很可能继续扩张,这对你这样一份还要长期维护的代码库是有意义的。

下一步很具体:如果你的框架已经锁定了某个 peer 依赖,就接受这个选择,继续往下走。如果没有,那就拿上面的检查清单对自己的应用过一遍,十分钟足够,然后选出那个默认值与你期望的数据行为一致的库。如果你想要一个已经做好这个决定的开箱即用脚手架,TanStack Ship 模板里包含搭配 Cloudflare Workers 的 TanStack Query 配置,定价页列出了各个层级。

本站的这篇文章以 canonical URL 和 BlogPosting JSON-LD 提供,因此这些元数据会进入搜索结果和 AI 回答。

更多资料