react-query-devtools：实践指南

作者：袖梨 2026-09-11

面对实际交付，我看react-query-devtools的重点不在星标，而在这项能力：⚛ 用于 React 查询的开发工具。实际做界面与前端开发时，经常会碰到视觉还原、交互状态和响应式细节容易遗漏，所以功能列表并不能代替验证。与其反复读介绍，不如选一个包含多状态的真实组件完成实现，再依据尺寸、状态、可访问性、资源和不同视口表现做取舍。它更像给愿意逐状态验收界面质量的前端团队准备的可审查方案，是否长期使用应由试跑数据决定。

DEPRECATED

此存储库和包已被弃用，取而代之的是随 React Query v3 一起提供的新内置开发工具。对于仍在使用 v2 的人来说，这个存储库将保留在这里。

文档

安装
用途
- 浮动模式
- 嵌入模式

安装

$ npm i --save react-query-devtools
# or
$ yarn add react-query-devtools

使用 React Native？尝试使用 react-query-native-devtools 代替。

用途

默认情况下，当 process.env.NODE_ENV === 'production' 时，不会导入和使用 React Query Devtools，因此您无需担心在生产构建期间排除它们。

如果您想在生产中使用开发工具，您可以通过直接导入 dist/react-query-devtools.production.min.js 文件来手动导入它们（最好是异步代码分割）。

浮动模式

浮动模式会将开发工具安装为应用程序中的固定浮动元素，并在屏幕一角提供切换开关以显示和隐藏开发工具。此切换状态将在重新加载时存储并记住在 localStorage 中。

将以下代码尽可能放置在 React 应用程序的较高位置。它离页面根部越近，效果就越好！

import { ReactQueryDevtools } from 'react-query-devtools'

function App() {
  return (
    <>
      {/* The rest of your application */}
      <ReactQueryDevtools initialIsOpen={false} />
    </>
  )
}

选项

initialIsOpen: Boolean
- 如果您希望开发工具默认打开，请设置此 true
panelProps: PropsObject
- 使用它可以将道具添加到面板中。例如，您可以添加className、style（合并并覆盖默认样式）等。
closeButtonProps: PropsObject
- 使用它向关闭按钮添加道具。例如，您可以添加 className、style（合并并覆盖默认样式）、onClick（扩展默认处理程序）等。
toggleButtonProps: PropsObject
- 使用它可以将道具添加到切换按钮。例如，您可以添加 className、style（合并并覆盖默认样式）、onClick（扩展默认处理程序）等。
位置？：“左上角” | “右上角” | “左下角” | “右下角”
- 默认为 bottom-left
- 用于打开和关闭 devtools 面板的 React Query 徽标的位置

嵌入模式

嵌入式模式会将开发工具作为常规组件嵌入到您的应用程序中。之后您可以随心所欲地设计它！

import { ReactQueryDevtoolsPanel } from 'react-query-devtools'

function App() {
  return (
    <>
      {/* The rest of your application */}
      <ReactQueryDevtoolsPanel style={styles} className={className} />
    </>
  )
}

选项

使用这些选项来设计开发工具的样式。