用途
本技能用于指导在 TanStack Query 中集成持久化（persistQueryClient）与离线能力，涉及 PersistQueryClientProvider、createSyncStoragePersister、createAsyncStoragePersister 等 API，以及实验性的细粒度相关能力。适用于需要将查询缓存持久化到存储、并在离线或恢复场景下继续工作的 React 应用。
主要能力
- 通过 PersistQueryClientProvider 包裹应用，在恢复（restore）进行期间阻止查询发起请求。
- 使用 createSyncStoragePersister 配合 window.localStorage 创建同步存储持久化器。
- 通过 queryClient.resumePausedMutations() 在恢复后继续被暂停的 mutation。
- 使用 setMutationDefaults 为持久化的 mutation 提供可序列化的 mutationKey 与默认 mutationFn。
- 通过 networkMode: 'offlineFirst' 支持离线优先的写入。
- 将 gcTime 与持久化 maxAge 对齐，避免持久化数据在可恢复前被垃圾回收。
使用方式
基础 Setup：创建 QueryClient 并设置 defaultOptions.queries.gcTime（示例为 24 小时），使用 createSyncStoragePersister 创建 persister，再用 PersistQueryClientProvider 传入 client 与 persistOptions={{ persister }} 包裹子组件。
恢复暂停的 mutation：定义 queryClient 后，用 setMutationDefaults(['todos'], { mutationFn }) 设置默认 mutationFn，再调用 queryClient.resumePausedMutations()。
对齐缓存生命周期：在 QueryClient 的 defaultOptions.queries.gcTime 中设置与持久化匹配的时长（示例为 7 天）。
离线优先写入：在 useMutation 中设置 mutationKey 与 mutationFn，并指定 networkMode: 'offlineFirst'。
常见错误
- HIGH：gcTime 短于 maxAge。错误做法是将 gcTime 设为 5 分钟；正确做法是设为 24 小时。原因是持久化数据可能在 persister 的 maxAge 恢复之前被垃圾回收。
- CRITICAL：在恢复完成前渲染。错误做法是直接使用 QueryClientProvider；正确做法是使用 PersistQueryClientProvider，因为持久化 provider 会在恢复进行期间阻止查询请求。
- CRITICAL：缺少默认 mutationFn。错误做法是仅创建 QueryClient；正确做法是调用 setMutationDefaults 设置 mutationFn。原因是暂停的持久化 mutation 在没有可序列化的 mutationKey 映射到默认 mutationFn 时无法恢复。
适用场景
需要在浏览器本地存储中持久化查询缓存、在页面重载或离线后恢复数据与暂停的 mutation、以及实现离线优先写入的 React 应用。
限制
资料未提供关于收费、价格、平台支持范围、性能效果或具体版本要求的信息。