React Query中gcTime最大可设置时长？30天缓存失效问题咨询

核心结论 #

React Query官方文档没有明确规定gcTime的最大可设置时长，但实际使用中不能超过JavaScript定时器的最大安全延迟值——2^31 - 1毫秒（约24.8天，即2147483647毫秒）。你设置的30天（2592000000毫秒）已经超出这个阈值，导致缓存被立即标记为可回收，这就是返回首页后缓存消失的原因；而3天的时长在阈值内，所以能正常工作。

问题原因 #

React Query内部依赖JavaScript的setTimeout来管理缓存的垃圾回收时机。当传入的延迟值超过2^31 - 1时，浏览器会将定时器强制设置为0，相当于立即触发缓存清理逻辑，哪怕你配置的是30天，实际效果也是缓存被立刻回收。

解决方案 #

如果需要超过24.8天的长期缓存，不建议单纯依赖gcTime，可以通过以下方式实现：

• 持久化缓存：使用React Query的持久化插件（结合localStorage或sessionStorage）将缓存数据存到本地，这样即使页面刷新或关闭，数据也不会丢失，gcTime的限制就不再影响。
• 拆分缓存逻辑：如果不需要持久化，也可以将长周期拆分为多个短周期的缓存检查，但这种方式可靠性较低，优先推荐持久化方案。

代码调整建议 #

如果一定要用gcTime，先把值控制在安全阈值内：

const useGetCards = (deck_id: string, deck: DeckType | null) => {
  const queryKey = ["cards", deck_id];
  // 最大安全gcTime：约24.8天
  const MAX_SAFE_GCTIME = 2147483647;

  return useQuery({
    queryKey: queryKey,
    queryFn: () => getCards(deck_id, deck),
    refetchOnWindowFocus: false,
    refetchOnReconnect: true,
    retry: 0,
    gcTime: MAX_SAFE_GCTIME,
  });
};

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