开发工具

🎉 React Query 自带专用的 DevTools（开发工具）！🥳

在你开始使用 React Query 时，这些 DevTools 将成为你的得力助手。它们能够直观地展示 React Query 的内部运行状态，并在遇到问题时帮你节省大量调试时间！

请注意，目前 DevTools 不支持 React Native。

🎉 好消息！

我们现在有一个专门支持 React Native 的 React Query DevTools！它提供原生支持，允许你将 DevTools 直接集成到 React Native 项目中。查看详情并贡献代码：react-native-react-query-devtools。

此外，还有一个外部工具，允许你通过外部仪表盘使用 React Query DevTools。了解详情并贡献代码：react-query-external-sync。

新增功能

从 React Query v5 版本开始，DevTools 现在支持观察 mutations。

安装和导入 DevTools

DevTools 作为一个独立的包，你需要先安装它：

npm i @tanstack/react-query-devtools
pnpm add @tanstack/react-query-devtools
yarn add @tanstack/react-query-devtools
bun add @tanstack/react-query-devtools

如果你在 Next.js 13+ App Dir 中使用它，你需要将其安装为开发依赖（devDependency），否则可能无法正常工作。

然后，你可以这样导入 DevTools：

import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

默认情况下，React Query DevTools 仅在 process.env.NODE_ENV === 'development' 时才会被包含到构建中。因此，你不需要手动在生产环境中排除它。

浮动模式（Floating Mode）

浮动模式会将 DevTools 作为固定的浮动元素挂载到应用中，并在屏幕角落提供一个切换按钮来显示或隐藏 DevTools。这个状态会存储在 localStorage，在页面重新加载后仍然有效。

建议将以下代码放在 React 应用中尽可能靠近根节点的位置：

import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* 你的应用内容 */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

浮动模式选项

选项	类型	默认值	说明
initialIsOpen	boolean	false	是否默认展开 DevTools
buttonPosition	"top-left" | "top-right" | "bottom-left" | "bottom-right" | "relative"	"bottom-right"	切换按钮的位置
position	"top" | "bottom" | "left" | "right"	"bottom"	DevTools 面板的位置
client	QueryClient	最近的 QueryClient	使用自定义 QueryClient
errorTypes	{ name: string; initializer: (query: Query) => TError}[]	-	预定义可在 UI 触发的错误
styleNonce	string	-	用于 CSP（内容安全策略）的 nonce 值
shadowDOMTarget	ShadowRoot	-	指定 DevTools 的样式是否应用在 Shadow DOM

嵌入模式（Embedded Mode）

嵌入模式会将 DevTools 固定在你的应用内部，让你可以将 DevTools 面板嵌入到自定义的开发工具界面中。

示例代码

import { ReactQueryDevtoolsPanel } from "@tanstack/react-query-devtools";

function App() {
  const [isOpen, setIsOpen] = React.useState(false);

  return (
    <QueryClientProvider client={queryClient}>
      {/* 你的应用内容 */}
      <button onClick={() => setIsOpen(!isOpen)}>{isOpen ? "关闭" : "打开"} DevTools 面板</button>
      {isOpen && <ReactQueryDevtoolsPanel onClose={() => setIsOpen(false)} />}
    </QueryClientProvider>
  );
}

嵌入模式选项

选项	类型	默认值	说明
style	React.CSSProperties	{ height: '500px' }	自定义样式
onClose	() => unknown	-	关闭 DevTools 时的回调函数
client	QueryClient	最近的 QueryClient	使用自定义 QueryClient
errorTypes	{ name: string; initializer: (query: Query) => TError}[]	-	预定义可在 UI 触发的错误
styleNonce	string	-	用于 CSP（内容安全策略）的 nonce 值
shadowDOMTarget	ShadowRoot	-	指定 DevTools 的样式是否应用在 Shadow DOM

在生产环境中使用 DevTools

默认情况下，DevTools 不会包含在生产环境的构建中。但如果你希望在生产环境中懒加载 DevTools，可以使用 React.lazy：

import React from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { Example } from "./Example";

const queryClient = new QueryClient();

const ReactQueryDevtoolsProduction = React.lazy(() =>
  import("@tanstack/react-query-devtools/build/modern/production.js").then((d) => ({ default: d.ReactQueryDevtools }))
);

function App() {
  const [showDevtools, setShowDevtools] = React.useState(false);

  React.useEffect(() => {
    // @ts-expect-error
    window.toggleDevtools = () => setShowDevtools((old) => !old);
  }, []);

  return (
    <QueryClientProvider client={queryClient}>
      <Example />
      {showDevtools && (
        <React.Suspense fallback={null}>
          <ReactQueryDevtoolsProduction />
        </React.Suspense>
      )}
    </QueryClientProvider>
  );
}

export default App;

这样，你可以在控制台执行：

window.toggleDevtools();

来动态下载并显示 DevTools。

---

现代构建工具支持

如果你的构建工具支持 package exports，可以使用更简洁的导入路径：

const ReactQueryDevtoolsProduction = React.lazy(() =>
  import("@tanstack/react-query-devtools/production").then((d) => ({
    default: d.ReactQueryDevtools
  }))
);

TypeScript 用户注意 你需要在 tsconfig.json 中将 moduleResolution 设置为 "nodenext"，并且 TypeScript 版本需要 >=4.7。