React Query中persistQueryClient的工作原理是什么？

核心作用 #

简单说，persistQueryClient 就是帮你把 React Query 缓存里的 API 数据存到浏览器本地（比如 localStorage），刷新页面后不用重新发请求，直接从本地把缓存捞回来用，解决刷新丢失状态的问题。

工作流程 #

拆解成两步就懂了：

• 存数据：它会盯着 React Query 的缓存，只要缓存有更新（比如请求成功拿到新数据、用户修改了缓存数据），就自动把缓存转换成 JSON 字符串，存到你指定的本地存储里。
• 读数据：每次页面加载时，它先去本地存储里找之前存的缓存，把 JSON 转成 JS 对象，再塞回 React Query 的缓存里。这样你的组件一渲染，就能直接用之前的数据，不用等 API 请求。

关键组件怎么搭 #

要让它跑起来，三个核心部分缺一不可：

1. QueryClient：原来你用来管理缓存的客户端，需要配置好缓存过期时间（staleTime、cacheTime）。
2. Persister（存储适配器）：指定用什么存数据，比如createSyncStoragePersister可以直接用 localStorage/sessionStorage，还能自定义存储的键名。
3. PersistQueryClientProvider：替代原来的QueryClientProvider，把 QueryClient 和 persister 绑在一起，启动持久化监听。

最简示例代码 #

import { QueryClient, PersistQueryClientProvider } from '@tanstack/react-query'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

// 1. 创建QueryClient，配置缓存规则
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 缓存5分钟内视为“新鲜”，不用重新请求
      cacheTime: 30 * 60 * 1000, // 缓存30分钟后才会被清理
    },
  },
})

// 2. 创建存储适配器，用localStorage存，键名叫react-query-cache
const persister = createSyncStoragePersister({
  storage: window.localStorage,
  key: 'react-query-cache',
})

// 3. 用PersistQueryClientProvider包裹整个应用
function App() {
  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{ persister }}
    >
      {/* 你的页面/组件都放这里面 */}
    </PersistQueryClientProvider>
  )
}

踩坑注意点 #

• 敏感数据别乱存：localStorage 是明文存在浏览器里的，像用户 token 这种敏感数据别用它存，换成 sessionStorage 或者更安全的方式。
• 序列化限制：JSON 没法序列化函数、Symbol 这些特殊类型，所以你的缓存数据里不能有这些，否则存的时候会出错。
• 缓存过期依然生效：持久化只是帮你保存缓存，React Query 原来的 staleTime 和 cacheTime 规则还是会执行——比如缓存过期后，页面加载时会先显示旧数据，同时偷偷发请求更新缓存。
• 版本兼容：如果你的 API 数据结构改了，记得给 persister 加个 version 参数，避免旧缓存导致页面显示异常。

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