React Query：如何在首次进入页面时始终重新获取数据并缓存至页面刷新？

核心配置思路 #

要实现「首次进入页面强制拉新，后续缓存数据直到页面刷新/重新进入，且不展示过期数据」，可以通过组合React Query的以下配置项达成：

• 禁用 stale 数据展示：设置 staleTime: 0（默认值），数据一获取就会被标记为 stale，配合其他配置避免自动后台刷新时展示旧数据。
• 控制组件挂载时的拉新策略：设置 refetchOnMount: true，确保每次进入页面（组件挂载）时重新获取数据；同时设置 refetchOnWindowFocus: false，避免窗口聚焦时自动拉取。
• 缓存保留到页面刷新：设置 cacheTime: Infinity（或足够大的数值，比如 1000 * 60 * 60 * 24），让数据一直保留在内存缓存中，直到页面刷新（刷新后内存缓存清空）。
• 加载状态处理：使用 isLoading 状态控制展示加载组件，新数据加载完成前不展示旧数据。组件重新挂载触发拉新时，isLoading 会变为 true，此时仅展示加载状态，等新数据返回后再更新UI。

代码示例 #

import { useQuery } from '@tanstack/react-query';

const fetchYourData = async () => {
  const response = await fetch('/api/your-data');
  if (!response.ok) {
    throw new Error('数据获取失败');
  }
  return response.json();
};

const YourComponent = () => {
  const { data, isLoading, error } = useQuery({
    queryKey: ['yourDataKey'], // 唯一标识查询的key
    queryFn: fetchYourData,
    staleTime: 0, // 数据立即标记为stale，确保下次挂载触发拉新
    cacheTime: Infinity, // 数据一直缓存到页面刷新
    refetchOnMount: true, // 组件挂载时强制拉新
    refetchOnWindowFocus: false, // 窗口聚焦时不自动拉新
    refetchOnReconnect: false, // 网络重连时不自动拉新
  });

  if (isLoading) {
    return <div>加载中...</div>; // 仅展示加载状态，不显示旧数据
  }

  if (error) {
    return <div>数据加载失败：{error.message}</div>;
  }

  return (
    <div>
      {/* 渲染最新数据 */}
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </div>
  );
};

export default YourComponent;

关键配置说明 #

• queryKey：必须唯一，React Query通过它管理缓存的数据集。
• staleTime: 0：确保缓存数据立即被标记为过期，下次组件挂载时会触发重新获取。
• cacheTime: Infinity：让数据一直保存在内存中，直到页面刷新（浏览器内存释放）。
• refetchOnMount: true：每次进入页面（组件挂载）都会强制发起新请求，保证用户看到最新数据。
• isLoading 状态：请求过程中仅展示加载UI，完全避免展示过期缓存数据。

这样配置后，首次进入页面会拉新数据；用户离开再返回时，会重新发起请求并展示加载状态，直到新数据返回；页面刷新后缓存清空，再次进入又会重新拉新。

内容的提问来源于stack exchange，提问作者Guy Ben David