用途：协调 TanStack Query 作为外部数据缓存与 TanStack Router 的 loader 系统。Router 负责在导航时触发数据获取，Query 负责缓存、后台重新获取与数据生命周期。使用前需熟悉 TanStack Router 与 TanStack Query，建议先阅读 router-core 与 react-router。
主要能力与用法：
- 在路由上下文中配置 QueryClient。客户端方案用 createRouter 的 context 传入 queryClient，并通过 Wrap 包裹 QueryClientProvider；根路由用 createRootRouteWithContext<{ queryClient: QueryClient }>()({...}) 声明上下文（注意双括号工厂写法）。
- SSR 安全：必须在 createRouter 工厂函数内部创建 QueryClient，模块级单例会在服务端请求间泄漏数据。
- 自动 SSR：安装 npm install @tanstack/react-router-ssr-query，调用 setupRouterSsrQueryIntegration({ router, queryClient })，可自动脱水/注水、流式传输服务端解析的查询，并处理查询/变更抛出的 redirect()。也可手动用 dehydrate/hydrate 配置。
- 推荐模式：loader 中用 context.queryClient.query({ ...queryOptions, staleTime: 'static' }) 预取，组件用 useSuspenseQuery 订阅缓存获得后台更新；动态参数通过 queryOptions(params.postId) 构造。
- 流式模式：非关键数据用 void context.queryClient.query({...}).catch(noop) 即发即弃，组件用 useQuery 显示加载态；关键数据仍用静态查询阻塞。
- 错误处理：结合 useQueryErrorResetBoundary 与 router.invalidate() 实现重试。
关键限制与常见错误：必须设置 defaultPreloadStaleTime: 0，否则 Router 内置预加载缓存（默认 30 秒）会阻止 Query 控制数据新鲜度；SSR 下不可用模块级 QueryClient 单例；不要在 loader 中 await 即发即弃查询，否则阻塞导航、失去流式收益；createRootRouteWithContext 需双括号调用。Router 自身的 staleTime/gcTime 仍作用于 loader 返回值，纯 Query 模式可从 loader 返回空、仅靠 useSuspenseQuery 读取数据。
适用场景：使用 TanStack Router 与 TanStack Query 构建 React 应用，需要导航期预取、缓存协调、SSR 脱水/注水与流式渲染的前端项目。