ErrorBoundary结合TanStack useQuery无法触发的问题求助

核心排查点与修复步骤 #

1. 正确关联useQueryErrorResetBoundary与ErrorBoundary #

useQueryErrorResetBoundary必须在ErrorBoundary内部组件中调用，才能让React Query的重置逻辑和错误边界绑定。如果重置方法在ErrorBoundary外部获取，会导致错误无法被捕获或重置失效。

正确的App.tsx结构示例：

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
import { useQueryErrorResetBoundary } from '@tanstack/react-query';
import QueryComponent from './QueryComponent';

const queryClient = new QueryClient();

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div className="error-fallback">
      <h2>请求出错：{error.message}</h2>
      <button onClick={resetErrorBoundary}>重试请求</button>
    </div>
  );
}

// 单独抽离包裹组件，确保重置方法在ErrorBoundary内部获取
function QueryWrapper() {
  const resetQueryErrors = useQueryErrorResetBoundary();

  return (
    <ErrorBoundary
      fallbackRender={ErrorFallback}
      onReset={resetQueryErrors}
    >
      <QueryComponent />
    </ErrorBoundary>
  );
}

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <QueryWrapper />
    </QueryClientProvider>
  );
}

export default App;

2. 确保useQuery配置触发错误边界 #

必须同时开启throwOnError并正确设置useErrorBoundary，React Query才会将错误抛给上层ErrorBoundary，而非自行处理。

正确的QueryComponent.tsx示例：

import { useQuery } from '@tanstack/react-query';

// 模拟返回404的请求
const fetchData = async () => {
  const res = await fetch('https://example.com/api/404');
  if (!res.ok) {
    const error = new Error('资源不存在');
    // 给错误附加响应状态，用于后续判断
    (error as any).response = { status: res.status };
    throw error;
  }
  return res.json();
};

export default function QueryComponent() {
  const { data } = useQuery({
    queryKey: ['demo-data'],
    queryFn: fetchData,
    throwOnError: true, // 强制抛出错误，必须开启
    useErrorBoundary: (error) => {
      // 匹配404状态码，或直接返回true触发所有错误
      return (error as any).response?.status === 404;
    },
  });

  return <div>{data?.content || '加载中...'}</div>;
}

3. 避免错误被内部逻辑拦截 #

如果请求函数内部有try/catch，必须重新抛出错误，否则React Query无法捕获到错误，自然不会触发ErrorBoundary：

// 错误示例：捕获错误但未重新抛出
const fetchData = async () => {
  try {
    const res = await fetch('https://example.com/api/404');
    if (!res.ok) throw new Error('404');
    return res.json();
  } catch (err) {
    console.log(err); // 仅打印，未抛出
  }
};

// 正确示例：重新抛出错误给React Query处理
const fetchData = async () => {
  try {
    const res = await fetch('https://example.com/api/404');
    if (!res.ok) {
      const error = new Error('资源不存在');
      (error as any).response = { status: res.status };
      throw error;
    }
    return res.json();
  } catch (err) {
    throw err; // 重新抛出，让React Query处理
  }
};

4. 排查层级与兼容性问题 #

• 不要在QueryComponent内部嵌套ErrorBoundary，确保错误边界直接包裹使用useQuery的组件
• 确认React版本≥16.8（支持Hooks），react-error-boundary@4.x与@tanstack/react-query@4.29.5版本兼容

内容的提问来源于stack exchange，提问作者beeboop