NextJS+React Query(Suspense模式)捕获Axios未捕获错误的问题

核心原因 #

React Query在Suspense模式下依赖React错误边界（Next.js的error.js）捕获渲染阶段的错误，但如果Axios未正确抛出HTTP状态码错误，或错误被意外吞掉，就会导致控制台显示“未捕获”错误。

解决方案 #

1. 配置Axios主动抛出HTTP错误 #

Axios默认仅在网络故障时抛出错误，对4xx/5xx状态码会返回成功响应。需要修改配置，让Axios对非2xx状态码抛出错误：

// 创建Axios实例时配置validateStatus
import axios from 'axios';

const apiClient = axios.create({
  validateStatus: (status) => status < 400, // 仅当状态码小于400时视为成功
});

这样404错误会被Axios主动抛出，React Query才能识别并传递给错误边界。

2. 确保React Query的错误被传递到错误边界 #

在使用useSuspenseQuery（Next.js 13+推荐）时，不要在组件内用try/catch包裹查询逻辑——Suspense模式下，错误会自动被React抛出到最近的错误边界（error.js），手动捕获会打断这个流程，导致错误变成“未捕获”。

正确的查询示例：

'use client';
import { useSuspenseQuery } from '@tanstack/react-query';
import apiClient from './api-client';

export default function Home() {
  const { data } = useSuspenseQuery({
    queryKey: ['fetch-data'],
    queryFn: async () => {
      const res = await apiClient.get('/api/your-endpoint');
      return res.data;
    },
    // 可选：用onError记录错误，但不要吞掉错误
    onError: (error) => {
      console.log('请求错误:', error); // 仅记录，不处理
    },
  });

  return <div>{data}</div>;
}

3. 检查error.js的配置与位置 #

• error.js必须添加'use client'指令，因为错误边界是客户端组件：

  'use client';
  
  export default function Error({ error, reset }) {
    return (
      <div className="p-8">
        <h2 className="text-xl font-bold mb-4">请求失败</h2>
        <p>{error.message}</p>
        <button onClick={() => reset()} className="mt-4 px-4 py-2 bg-blue-500 text-white">
          重试
        </button>
      </div>
    );
  }
  

• 确保error.js放在正确的路由层级：比如Home组件在app/目录下，error.js也要放在app/目录，才能覆盖该路由下的所有组件错误。

4. 避免全局错误监听干扰 #

如果项目中存在全局错误监听（如window.addEventListener('error')），确保它不会阻止React错误边界的捕获逻辑，不要在监听中调用event.preventDefault()或吞掉错误。

验证方法 #

1. 触发404请求后，检查error.js是否正确渲染错误页面
2. 查看控制台：此时错误应该被标记为“已捕获”（或不再显示“未捕获”提示）

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