TanStack Query随机进入paused状态问题求助

问题概况 #

• 技术栈：Next.js 13.0.3、React 18.2.0、TanStack Query 4.22.0
• 触发场景：本地开发每周出现1-2次，生产环境首次出现；部分用户的特定Query在页面初始加载时直接进入paused状态，永远不发起请求
• 异常表现：页面能正常加载、用户可操作，但刷新页面、跳转路由都无法恢复paused的Query，只有重启电脑才能解决
• 初始配置：

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: Infinity,
      refetchOnWindowFocus: false,
    },
  },
});

• 修复方式：添加networkMode: "always"后问题彻底解决

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: Infinity,
      refetchOnWindowFocus: false,
      networkMode: "always"
    },
  },
});

根本原因 #

这个问题在TanStack Query社区有不少开发者遇到过，核心出在网络状态检测的误判+状态缓存：

1. 浏览器navigator.onLine API的局限性
   TanStack Query默认使用networkMode: "online"，依赖浏览器的navigator.onLine判断网络状态。但这个API只能检测设备是否连接到本地网络，无法判断能否正常访问互联网。比如VPN断连未切换、路由器DNS故障、网卡临时异常时，设备显示"在线"但实际发不出请求，或者浏览器误判为"离线"，且错误状态不会自动更新。

2. Query状态的缓存逻辑
   当navigator.onLine被误判为离线时，TanStack Query会把对应Query标记为paused。再加上你设置了staleTime: Infinity（数据永不过期）、refetchOnWindowFocus: false（窗口聚焦不重新请求），没有任何机制触发重新检查网络状态或重试请求。刷新页面时，浏览器的网络状态检测可能仍卡在错误状态，所以问题持续存在，直到重启电脑重置系统网络相关状态，navigator.onLine才恢复正常。

3. 仅部分Query受影响的原因
   只有特定Query出问题，是因为这些Query的初始化时机刚好撞上网络状态误判的窗口，且它们的缓存策略让它们没有机会触发重新检查逻辑，不像其他有重新获取触发条件的Query能自动恢复。

为什么networkMode: "always"能解决问题 #

设置这个参数后，TanStack Query会完全忽略浏览器的网络状态检测结果，强制发起请求，直接绕过了navigator.onLine误判带来的问题，这也是官方针对网络状态检测不准场景给出的标准解决方案之一。

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