用途：TanStack Query v5（2023 年 10 月发布）是项目的异步状态管理器，要求 React 18+，提供一等 Suspense 支持、更好的 TypeScript 推断和更小的包体积。核心理念是它不负责发请求，而是由你提供 Promise，它管理缓存、后台更新与同步。
主要能力与 v5 变更：所有 hook 改为单一对象签名；cacheTime 改名为 gcTime，keepPreviousData 改为 placeholderData: keepPreviousData，isLoading 含义改为 isPending && isFetching；useQuery 移除 onSuccess/onError/onSettled 回调，改用全局 QueryCache 回调；无限查询必须显式提供 initialPageParam；新增 useSuspenseQuery 等专用 hook。迁移可用命令：npx @tanstack/query-codemods v5/replace-import-specifier。
必要用法：通过 QueryClientProvider 提供 QueryClient，可在 defaultOptions 配置 staleTime、gcTime、retry 等；开发时挂载 ReactQueryDevtools。SSR 场景（Next.js、Remix）需调整默认值：服务端 retry 为 0、staleTime 60_000+、gcTime 为 Infinity、关闭窗口聚焦与重连刷新。
推荐模式：按功能共置查询逻辑；使用查询键工厂分层组织键，键必须包含 queryFn 中所有变量，注意类型一致性；用 queryOptions 统一配置以获得类型安全；数据转换优先用 select 并记忆化；始终封装自定义 hook；错误处理分组件级、全局 QueryCache 与 Error Boundary 三层。
限制：服务端默认与流式 SSR（@tanstack/react-query-next-experimental）仅适用于 Next.js App Router 等 SSR 框架，不适用于纯 SPA。文档内容在某处被截断，后续部分暂未提供。