TanStack QueryReact QueryNetwork Mode 全解析online / always / offlineFirst 三种联网模式的实现原理与实战配置【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/queryTanStack Query本仓库中对应tanstack/react-query、query-core等包内置了三档networkMode用于精确控制断网时 Query 与 Mutation 的行为是直接不执行、照常执行还是先执行一次再暂停重试。本文以 Network Mode 指南 为骨架逐一拆解online、always、offlineFirst三种模式的语义、默认值与适用场景并结合query-core源码retryer.ts、onlineManager.ts、query.ts讲清fetching / paused / idle与fetchStatus的底层切换逻辑帮助你为离线 PWA、本地存储查询和普通在线应用选择正确的联网策略。三种网络模式速览TanStack Query 通过NetworkMode这一联合类型来区分在线 / 离线行为其定义位于 types.tsexport type NetworkMode online | always | offlineFirst模式无网络时是否首次执行queryFn失败后重试refetchOnReconnect默认值典型场景online默认不执行进入paused暂停待恢复连接后继续true绝大多数在线数据请求always总是执行不暂停失败直接进入errorfalse读本地AsyncStorage/ 纯内存计算无需真实网络offlineFirst执行一次首次失败后暂停重试trueService Worker 离线缓存、Cache-ControlHTTP 缓存设置层级为“单条 Query / Mutation 局部配置或通过 Query / Mutation 的全局默认值统一配置”默认值固定为online。该类型同时被 QueryOptions 与 MutationOptions 引用因此 Query 与 Mutation 两套体系共享同一套联网语义。如何配置 networkMode单条 Query 上设置最常见的做法是直接在useQuery的选项中声明import { useQuery } from tanstack/react-query // 本地优先即使断网也尝试读取本地缓存 useQuery({ queryKey: [local-counter], queryFn: async () { const stored await readFromAsyncStorage(counter) if (stored ! null) { return stored } throw new Error(cache miss, need network) }, networkMode: offlineFirst, }) // 强制忽略在线状态 useQuery({ queryKey: [computed-value], queryFn: () Promise.resolve(5), // 根本不需要网络 networkMode: always, })单条 Mutation 上设置Mutation 与 Query 使用同一选项名import { useMutation } from tanstack/react-query const sendLog useMutation({ mutationFn: (payload) api.send(payload), networkMode: always, // 例如发送到本地队列不依赖真实网络 })全局默认值既可以通过QueryClient的defaultOptions全局兜底也可以配合queryClient.setQueryDefaults/setMutationDefaults按queryKey命中局部默认值import { QueryClient } from tanstack/react-query const queryClient new QueryClient({ defaultOptions: { queries: { networkMode: online }, // 全部查询默认值 mutations: { networkMode: online }, // 全部变更默认值 }, }) queryClient.setQueryDefaults([user, preferences], { networkMode: offlineFirst })关于默认值还有一个容易被忽略的依赖规则在queryClient.defaultQueryOptions内部当显式传入persister而未显式声明networkMode时会自动将其推导为offlineFirst见 queryClient.ts这为持久化persist场景提供了合理的默认联网行为具体在“与 Persister 的联动”一节展开。Network Mode: online默认最常用online模式下没有网络连接时 Query 与 Mutation 不会触发。这是默认模式也是绝大多数数据获取库的合理选择。如果某个查询在断网情况下被请求获取数据它会在statepending/error/success中保持不变——也就是说查询并不会凭空失败而是停留在当前状态等待网络恢复。与此同时查询额外暴露了一维fetchStatus用来描述“fetch 管道本身的运行情况”可能取值如下fetchingqueryFn真正在执行请求正在飞行中in-flightpaused查询未在执行因断网而暂停直到重新获得连接idle查询既没有在抓取也没有被暂停。为便于使用isFetching与isPaused两个布尔量由fetchStatus派生而来见 queryObserver.tsconst isFetching newState.fetchStatus fetching const isPaused newState.fetchStatus paused注意不要只看pending来渲染加载态指南中特别强调了一处反直觉陷阱首次挂载且断网时查询可能处于state: pending但fetchStatus: paused。此时若 UI 只判断isPending就去渲染 loading spinner页面会一直转圈而毫无意义因此判断是否展示加载指示器时应结合fetchStatusconst { isPending, fetchStatus } useQuery({ queryKey: [data], queryFn: fetchData }) const showSpinner isPending fetchStatus fetching // 而不是只看 isPending抓取过程中掉线暂停的是“重试”不是查询本身如果一个查询在在线时启动成功但请求尚未返回时设备突然断网TanStack Query 会暂停重试retry机制待网络恢复后再继续执行这是对中断 fetch 的继续continue而非一次全新的refetch。这在retryer中被实现为“可继续时继续否则挂起等待”其判定条件同时要求窗口聚焦且处于在线状态// packages/query-core/src/retryer.ts#L110-L113 const canContinue () focusManager.isFocused() (config.networkMode always || onlineManager.isOnline()) config.canRun()这条暂停/继续链路的关键点在于与refetchOnReconnect相互独立。refetchOnReconnect此模式下默认true触发的是“重连后的重新抓取”而这里发生的是一次“继续”动作。在 query.ts 的onOnline中可以看到两者同时被处理先按shouldFetchOnReconnect触发refetch再调用this.#retryer?.continue()唤醒被暂停的请求。如果查询在这期间被取消如组件卸载触发的静默取消详见 Query Cancellation那么它不会再继续——cancel会使底层 retryer 的 Promise 以CancelledError收尾。Network Mode: always始终执行忽略在线状态always模式下TanStack Query始终发起抓取并完全忽略在线/离线状态。指南给出两个典型例子queryFn内部只读取AsyncStorage或者直接返回Promise.resolve(5)——即“查询本身根本不需要真实网络”的场景。该模式的边界行为可从源码逐条得到印证查询永远不会因为断网而进入paused。canFetch对always直接返回true// packages/query-core/src/retryer.ts#L53-L57 export function canFetch(networkMode: NetworkMode | undefined): boolean { return (networkMode ?? online) online ? onlineManager.isOnline() : true }重试也不会暂停请求若失败将按重试策略默认最多 3 次见retryer.run中的config.retry ?? (isServerEnvironment() ? 0 : 3)走完最终使查询进入error状态不会卡在半路。refetchOnReconnect默认为false重连网络已不再是“陈旧数据应当刷新”的有效信号。这一默认值并非写死在选项里而是在 queryClient.ts 的 defaultQueryOptions 中按模式推导出来的if (defaultedOptions.refetchOnReconnect undefined) { defaultedOptions.refetchOnReconnect defaultedOptions.networkMode ! always }如果确实希望在always模式下依然响应重连可以手动将refetchOnReconnect重新打开。Network Mode: offlineFirst折中方案offlineFirst是前两种模式之间的折中TanStack Query 会让queryFn先执行一次但之后的重试会被暂停。这一点对两类缓存场景非常友好带 Service Worker 拦截请求的离线优先 PWA首屏请求可能命中 Service Worker 缓存而成功依赖Cache-Control头的 HTTP 缓存首次请求可能由浏览器 HTTP 缓存直接命中。在这种情形下如果第一次抓取来自离线存储/缓存并成功查询正常完成如果发生缓存未命中真实网络请求发出后失败此时该模式的表现退化为online——暂停后续重试等待网络恢复。这一“先试一次、失败再暂停”的策略同样可从源码验证retryer.start()中只要canFetch为真offlineFirst与always一样返回true首次就会真正run()一次只有进入失败重试路径的sleep之后才轮到canContinue/pause判定// packages/query-core/src/retryer.ts#L227-L235 start: () { // Start loop if (canStart()) { run() } else { pause().then(run) } return promise },底层实现retryer、OnlineManager 与恢复链路OnlineManager在线状态的唯一事实来源onlineManager是全局单例onlineManager.ts其内部默认#online true并通过订阅window上的online/offline事件来更新状态onlineManager.ts。暴露的核心接口为onlineManager.isOnline(): boolean——读取当前在线状态onlineManager.setOnline(online: boolean)——手动设置Devtools 的 Mock 按钮正是走这条路onlineManager.subscribe(listener)——订阅在线状态变化。关于默认在线状态的说明可参考 onlineManager 参考文档项目刻意不再依赖navigator.onLine作为初始值Chromium 系浏览器中它有大量误判为离线的历史问题而是默认online: true仅靠事件驱动更新以降低“假离线”误判概率代价是经 Service Worker 加载的离线应用可能短暂出现“假在线”因为它们确实可以在没有公网连接的情况下工作。pause / continue 与状态机在online模式下若断网启动查询canFetch返回falseretryer.start()进入pause()。pause()返回一个 Promise其continueFn只有在isResolved()或canContinue()成立时才会放行从而真正执行run()fetchStatus也随之在paused与fetching之间切换对应 query.ts 中的状态 dispatch。恢复连接的完整链路是window的online事件 →onlineManager广播 → Query 的onOnline()见 query.ts→ 触发refetchOnReconnect判断 retryer.continue()→ 被暂停的抓取/重试继续执行。Mutation 同样遵循 networkModeMutation 在构建其内部 retryer 时会把当前networkMode传入见 mutation.ts并且用!retryer.canStart()推导自身的 paused 状态mutation.ts因此 Mutation 也会在断网时暂停并在恢复后继续相关行为的完整指南见 Mutations。与 Persister 的联动自动降级为 offlineFirst使用createPersister/persistQueryClient这类持久化方案时写缓存通常依赖本地存储而不依赖网络。为了让持久化查询在“首次尝试本地读取、命中即成功、未命中才等网络”的语义下运行defaultQueryOptions加入了自动推导规则queryClient.tsif (!defaultedOptions.networkMode defaultedOptions.persister) { defaultedOptions.networkMode offlineFirst }即只要指定了persister且没有显式写死networkMode就会被自动设置为offlineFirst。这意味着离线优先的持久化读取几乎开箱即用若希望强制走online或always则需显式声明以覆盖该推导值。Devtools观察 paused 与模拟离线TanStack Query Devtools 会以paused状态展示“本想抓取、但因断网未能执行”的查询便于在开发阶段直接观察联网策略是否生效。Devtools 面板中还提供了一个Mock offline behavior模拟离线行为的切换按钮。请特别注意这个按钮并不会真的切断你的网络连接真正断网可在浏览器 Devtools 的 Network 面板完成它的实现只是把OnlineManager置为离线状态——源码中对应一次setOnline取反见 query-devtools 的 Devtools.tsxonlineManager().setOnline(!onlineManager().isOnline())正因如此通过该按钮可以零成本地验证你的 Query / Mutation 在三种networkMode下分别会表现出fetching、paused还是直接失败——与fetchStatus的观察相互印证。Signature配置签名速查networkMode的完整类型签名如下networkMode: online | always | offlineFirst可选默认值为online选型建议小结常规在线请求保持默认online并记得结合fetchStatus paused正确渲染加载/离线提示查询纯依赖本地数据AsyncStorage、内存计算always有 Service Worker 或Cache-Control缓存兜底、愿意“先试一次、失败再等网络”的离线优先 PWAofflineFirst接入了persister却未显式声明联网模式框架已自动使用offlineFirst无需重复配置。配合 QueriesfetchStatus与isPaused定义、Mutations 以及 query-core 源码 阅读本文即可完整掌握 TanStack Query 在离线场景下的行为边界。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考