如何在 React Query 中仅当数据过期时触发重新获取？

在 React Query 中，数据是否重新获取取决于缓存状态与配置项。通过设定 staleTime 可明确数据保持新鲜的时间，超过该时间后数据标记为过期，此后触发的相关查询才会真正请求接口。

理解 staleTime 与 gcTime

React Query 使用 staleTime 判断数据何时变旧。在 staleTime 时间内，数据被视为新鲜，不会主动发起重新获取。gcTime 控制缓存回收时间，与重新获取触发无直接关系。

基础配置示例

以下代码展示如何在 useQuery 中设置 staleTime，实现仅数据过期后重新获取：

import { useQuery, QueryClient, QueryClientProvider } from 'react-query';
import axios from 'axios';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // 五分钟内数据视为新鲜
      staleTime: 5 * 60 * 1000,
      refetchOnWindowFocus: true,
    },
  },
});

function useUser(id) {
  return useQuery(
    ['user', id],
    async () => {
      const { data } = await axios.get('https://ipipp.com/api/user/' + id);
      return data;
    }
  );
}

手动控制重新获取时机

若希望完全自己决定何时重新获取，可关闭自动刷新，并在数据过期后调用 refetch。

结合 isStale 判断

React Query 暂未直接暴露 isStale 字段，但可通过 queryClient 的 getQueryState 获取观测信息。

import { useQueryClient } from 'react-query';

function RefreshButton({ userId }) {
  const queryClient = useQueryClient();

  const handleClick = () => {
    const state = queryClient.getQueryState(['user', userId]);
    // dataUpdatedAt 加上 staleTime 小于当前时间说明已过期
    const isStale = state && Date.now() - state.dataUpdatedAt > 5 * 60 * 1000;
    if (isStale) {
      queryClient.refetchQueries(['user', userId]);
    }
  };

  return <button onClick={handleClick}>仅过期时刷新</button>;
}

使用 refetchInterval 的进阶做法

如果希望周期性检查，但仅过期才请求，可配合函数式 refetchInterval 返回 null 跳过新鲜数据。

useQuery(
  ['news'],
  fetchNews,
  {
    staleTime: 60000,
    refetchInterval: (query) => {
      // 数据新鲜时不轮询
      if (Date.now() - query.state.dataUpdatedAt < 60000) {
        return false;
      }
      return 30000;
    },
  }
);

总结

合理配置 staleTime 是避免多余请求的核心。配合 refetchOnWindowFocus、手动 refetch 与条件轮询，即可实现仅当数据过期时触发重新获取，既保证数据时效，也减少资源消耗。

React_QuerystaleTimerefetch修改时间：2026-07-26 00:27:18