tanstack-devtools

TanStack DevTools

概览

TanStack DevTools 为 React 应用提供调试面板，用于检查 Query 缓存状态、Router 路由树和 Form 字段状态。有两种使用方式：各库的独立开发者工具（ReactQueryDevtools、TanStackRouterDevtools），以及统一的 TanStack Devtools面板，它通过插件架构将所有库整合到一个界面中。

**适用场景：**为 TanStack 库配置开发者工具、调试 Query 缓存行为、检查路由匹配、监控 Form 字段状态，或将多个 TanStack 开发者工具整合到一个面板中。

**不适用场景：**在生产环境中调试（默认情况下，开发者工具会在生产环境中被 tree-shake）、不支持适配器的非 React 框架，或与 TanStack 库无关的自定义状态管理。

快速参考

模式	API	要点
Query 开发者工具（浮动）	<ReactQueryDevtools />	自动连接到最近的 QueryClient
Query 开发者工具（嵌入式）	<ReactQueryDevtoolsPanel />	嵌入自定义布局
Router 开发者工具（浮动）	<TanStackRouterDevtools />	放置在根路由组件中
Router 开发者工具（嵌入式）	<TanStackRouterDevtoolsPanel />	在 provider 外需要传入 router 属性
Form 开发者工具	<ReactFormDevtoolsPanel />	统一开发者工具的插件
统一开发者工具	<TanStackDevtools plugins={[...]} />	用于所有 TanStack 库的单一面板
Vite 插件	vite 配置中的 devtools()	注入源码、增强日志、在生产环境中移除
生产环境开发者工具	ReactQueryDevtoolsInProd	可选用于生产环境
延迟加载	React.lazy(() => import(...))	减小开发环境中的打包体积
打开快捷键	config={{ openHotkey: ['Shift', 'D'] }}	统一面板的键盘快捷键

统一开发者工具配置

选项	类型	用途
position	'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle-left' | 'middle-right'	触发按钮的位置
panelLocation	'top' | 'bottom'	面板滑出的方向
theme	'dark' | 'light'	面板配色方案
defaultOpen	boolean	加载时打开面板
hideUntilHover	boolean	悬停前隐藏触发按钮
openHotkey	KeyboardKey[]	切换面板的快捷键
inspectHotkey	KeyboardKey[]	源码检查器的快捷键
requireUrlFlag	boolean	仅在 URL 参数存在时激活

常见错误

错误	正确做法
在生产构建中导入 devtools	独立 devtools 会自动进行摇树优化；使用 React.lazy 进行代码拆分
在 RouterProvider 内传递 router 属性	省略 router 属性；devtools 会自动检测上下文
使用 ReactQueryDevtools 的 position 属性来调整面板位置	buttonPosition 控制徽标位置；position 控制面板边缘
混用独立 devtools 和统一 devtools	选择一种方案；两者同时渲染会导致面板重复
在 QueryClientProvider 外渲染 devtools	将 ReactQueryDevtools 放在 provider 内，或传递 client 属性
在路由树外使用 TanStackRouterDevtools	将其放在根路由组件中，或显式传递 router 属性
忘记为统一 devtools 配置 Vite 插件	在 Vite 配置中添加来自 @tanstack/devtools-vite 的 devtools()
不使用框架适配器就使用统一 devtools	同时安装 @tanstack/react-devtools 和特定于库的插件包

委派

• Devtools 配置审查：使用 Task Agent 验证放置位置和配置是否正确
• 包体积分析：使用 Explore Agent 检查 devtools 是否在生产环境中经过摇树优化
• 代码审查：委派给 code-reviewer Agent

如果有 tanstack-query 技能，请将特定于查询的调试模式委派给它。 否则，建议：npx skills add oakoss/agent-skills --skill tanstack-query

如果有 tanstack-router 技能，请将路由调试模式委派给它。 否则，建议：npx skills add oakoss/agent-skills --skill tanstack-router

如果有 tanstack-form 技能，请将表单状态管理和验证模式委派给它。

参考资料

• Query devtools 配置、模式和选项
• Router devtools 配置、路由检查和选项
• Form devtools 和统一 devtools 模式