如何让React Query持久缓存在线时强制从服务器获取数据？

一、针对React Query的配置调整建议 #

要实现「离线读缓存，在线从服务器获取并更新缓存」，可以调整以下配置：

• 开启refetchOnReconnect: true：取消代码中该配置的注释，让网络恢复时自动触发数据重拉，更新缓存。
• 确认networkMode设置：保持默认的'online'即可，该配置会让React Query在在线状态下优先发起网络请求，离线时 fallback 到缓存。
• 检查staleTime：你设置的2000ms（2秒）是合理的，超过这个时间后数据会被标记为「过期」，React Query会自动重新请求服务器更新数据。

修改后的QueryClient配置示例：

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      cacheTime: 1000 * 60 * 60 * 24, // 24 hours
      staleTime: 2000,
      retry: 0,
      refetchOnReconnect: true, // 开启重连后自动刷新
      networkMode: 'online', // 在线时优先请求服务器
    },
  },
});

另外，你在初始化时调用queryClient.invalidateQueries()和queryClient.clear()的时机可能有问题——这些操作会被PersistQueryClientProvider的缓存恢复覆盖，建议只保留onSuccess里的invalidateQueries逻辑，确保缓存恢复后触发一次全量刷新。

二、localStorage清除后缓存复现的原因 #

你清除REACT_QUERY_OFFLINE_CACHE后刷新页面，缓存又被填充，是因为浏览器的HTTP磁盘缓存在起作用：浏览器直接从本地磁盘返回了之前API请求的响应，React Query拿到这个旧响应后，又重新写入了localStorage。此时网络面板显示的(disk cache)就是明证，这和React Query的持久化缓存机制无关。

三、最终根因确认 #

2023年12月17日更新：团队成员修改了API的请求头（比如添加了强缓存的Cache-Control字段）但未同步说明，导致浏览器对API响应进行持久化磁盘缓存，在线时也不会向服务器发起新请求，而是直接返回缓存内容。

补充提示 #

React Query的localStorage持久化缓存和浏览器的HTTP磁盘缓存是两个完全独立的层级：

• 前者是框架层面的业务数据缓存，由React Query管理；
• 后者是浏览器层面的HTTP响应缓存，由请求头控制。
  遇到类似问题时，优先在浏览器网络面板查看请求的缓存状态和响应头，排查HTTP层面的缓存配置。

内容的提问来源于stack exchange，提问作者duduwe