
通过配置 staleTime、cacheTime 和 refetchOnWindowFocus 三项关键选项,可让 React Query 在首次加载后始终读取缓存数据,彻底避免页面刷新或浏览器标签切换时的重复请求。
通过配置 `staletime`、`cachetime` 和 `refetchonwindowfocus` 三项关键选项,可让 react query 在首次加载后始终读取缓存数据,彻底避免页面刷新或浏览器标签切换时的重复请求。
在使用 React Query 构建数据驱动型应用时,一个常见需求是:仅在首次访问页面时发起 API 请求,后续所有渲染(包括页面刷新、路由跳转、标签页切换)均直接从缓存读取,不触发任何网络请求。默认情况下,React Query 会在窗口重新获得焦点(如切回标签页)或组件重新挂载时尝试“重新验证”(refetch),这往往导致不必要的请求和 UI 闪烁。
要实现真正的“一次获取、长期复用”,需协同配置以下三个选项:
✅ 核心配置说明
| 选项 | 作用 | 推荐值 | 说明 |
|---|---|---|---|
staleTime |
数据被视为“新鲜”的毫秒数;超过则标记为 isStale = true,可能触发 refetch |
Infinity |
表示数据永不陈旧,永远跳过自动重新验证逻辑 |
cacheTime |
查询项在缓存中保留的毫秒数;超时后将被垃圾回收 | Infinity |
确保查询结果永驻内存,即使组件卸载也不会被清除 |
refetchOnWindowFocus |
窗口获得焦点时是否自动 refetch | false |
必须全局关闭,否则单个 query 配置无效(该行为由 QueryClient 统一控制) |
✅ 正确实现方式(分两步)
第一步:在 QueryClient 实例中全局禁用窗口聚焦刷新
// src/queryClient.ts
import { QueryClient } from '@tanstack/react-query';
export const queryClient = new QueryClient({
defaultOptions: {
queries: {
refetchOnWindowFocus: false, // ? 关键:全局关闭 tab 切换刷新
retry: false, // 可选:失败时不重试
},
},
});并在根组件中提供:
KeystoneJS 是一个功能强大的开源无头 CMS,适用于 Node.js,它根据您的模式定义自动生成 GraphQL API 和基于 React 的管理界面。由 Thinkmill 构建,支持 PostgreSQL 和 SQLite、自定义访问控制、钩子、虚拟字段和基于文档的富文本编辑。
// src/main.tsx 或 App.tsx
import { QueryClientProvider } from '@tanstack/react-query';
import { queryClient } from './queryClient';
function App() {
return (
<QueryClientProvider client={queryClient}>
<QueryCache />
</QueryClientProvider>
);
}第二步:在具体 useQuery 中锁定缓存策略
import { useQuery } from '@tanstack/react-query';
const QueryCache = () => {
const { data, isLoading, isFetching, error } = useQuery(
'todos', // queryKey
async () => {
const res = await fetch('https://jsonplaceholder.typicode.com/todos');
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
},
{
staleTime: Infinity, // ✅ 永不视为陈旧
cacheTime: Infinity, // ✅ 永不从缓存移除
// refetchOnWindowFocus 已在 QueryClient 全局设为 false,此处无需重复
}
);
if (isLoading) return <p>Loading...</p>;
if (error) return <p>Error: {(error as Error).message}</p>;
// isFetching === false 表示本次渲染完全来自缓存(无网络请求)
return (
<div>
<h2>Status: {isFetching ? 'Refetching (should NOT happen)' : 'Cached'}</h2>
<pre class="brush:php;toolbar:false;">{JSON.stringify(data?.slice(0, 3), null, 2)}
);
};
export default QueryCache;⚠️ 注意事项与最佳实践
-
staleTime: Infinity不等于“永不更新”:它只是禁用自动 revalidation;你仍可通过queryClient.invalidateQueries()或queryClient.refetchQueries()主动触发刷新。 -
内存管理需谨慎:
cacheTime: Infinity会使数据常驻内存,若缓存大量大体积响应,请评估内存占用,必要时改用有限时间(如1000 * 60 * 60 * 24即 24 小时)。 -
服务端数据变更怎么办? 若后端数据会动态更新且要求强一致性,此方案不适用——应改用合理的
staleTime(如5 * 60 * 1000)配合refetchOnMount: true,或引入 WebSockets/Server-Sent Events 主动推送变更。 -
SSR/SSG 场景:服务端渲染时,
staleTime默认为0,需显式传入staleTime: Infinity才能确保服务端生成的缓存也被客户端继承。
✅ 总结:真正“停止重载刷新”的关键不是只改单个 query,而是
QueryClient全局关掉refetchOnWindowFocus+ 单个 query 设置staleTime和cacheTime为Infinity。二者缺一不可。

















