NextJS 13如何通过默认React Error Boundary全局处理服务端错误？

核心原因 #

NextJS 的 error.js 本质是 React Error Boundary，而 React Error Boundary只能捕获组件渲染阶段抛出的错误，无法处理以下场景的错误：

• 事件处理函数（比如 onClick 回调）
• 异步代码（Promise、setTimeout/setInterval）
• 全局范围内的 JS 错误

你点击按钮触发的错误属于事件处理回调，不在 error.js 的捕获范围内，所以不会触发错误页面。

解决方案 #

1. 手动捕获事件错误，转成渲染阶段错误触发 error.js

通过状态管理错误状态，在组件渲染时判断并抛出错误，让 error.js 捕获：

'use client';

import { useState } from 'react';

const Home = () => {
  const [triggerError, setTriggerError] = useState(false);

  const ErrorTrigger = () => {
    try {
      throw new Error('Button click error');
    } catch (err) {
      setTriggerError(true);
    }
  };

  // 渲染阶段抛出错误，触发 error.js
  if (triggerError) {
    throw new Error('Button click error');
  }

  return <button onClick={ErrorTrigger}>Trigger Error</button>;
};

export default Home;

2. 模拟服务端 500 错误的处理

如果是模拟 API 服务端错误，先在 API 路由中抛出错误：

// app/api/server-error/route.js
export async function GET() {
  throw new Error('Server internal error (500)');
}

然后前端调用 API 时捕获错误，再触发渲染阶段错误：

'use client';

import { useState } from 'react';

const Home = () => {
  const [serverError, setServerError] = useState(false);

  const triggerServerError = async () => {
    try {
      const res = await fetch('/api/server-error');
      if (!res.ok) {
        throw new Error(await res.text());
      }
    } catch (err) {
      setServerError(true);
    }
  };

  if (serverError) {
    throw new Error('Server 500 Error');
  }

  return <button onClick={triggerServerError}>Trigger Server 500</button>;
};

export default Home;

3. 全局捕获客户端运行时错误

如果想统一处理所有客户端未捕获的错误（包括事件、异步），可以在根布局中添加全局错误监听：

'use client';

import { useEffect } from 'react';

export default function RootLayout({ children }) {
  useEffect(() => {
    const handleGlobalError = (event) => {
      console.error('Uncaught error:', event.error);
      // 这里可以显示全局错误弹窗，或者通过上下文传递错误状态触发 error.js
    };

    window.addEventListener('error', handleGlobalError);
    return () => window.removeEventListener('error', handleGlobalError);
  }, []);

  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  );
}

总结 #

error.js 是 NextJS 提供的渲染阶段错误捕获方案，对于运行时的事件、异步错误，需要手动捕获后转成渲染阶段错误，或者通过全局监听做统一处理。如果需要模拟服务端错误，要在 API 路由中抛出，前端调用时捕获再触发错误页面。

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