React ErrorBoundary为什么捕获不了异步错误

在使用 React 开发应用时，ErrorBoundary 是处理组件崩溃、防止白屏的最后一道防线。但在实际项目中，你可能会遇到一个令人头疼的问题：明明代码抛出了错误，ErrorBoundary 却毫无反应，页面依然崩溃。

这通常是因为错误发生在“异步”操作中。要解决这个问题，首先需要理解 ErrorBoundary 的工作机制，并学会如何将异步错误转化为它能够识别的形式。

1. 核心机制：ErrorBoundary 的盲区

ErrorBoundary 的核心原理是利用 React 的生命周期方法（如 componentDidCatch 或静态方法 getDerivedStateFromError）来捕获子组件在“渲染期间”抛出的错误。

React 的错误边界仅对以下两种情况有效：

1. 渲染时：组件渲染过程中发生的错误。
2. 生命周期方法中：在 constructor、render 等 React 主动调用的方法中发生的错误。

一旦 React 完成了渲染，将控制权交还给了浏览器（例如交给了 setTimeout、addEventListener 或者网络请求的回调），后续发生的任何错误都已经脱离了 React 的调用栈。因此，ErrorBoundary 根本“感知”不到这些错误。

为了直观理解这种差异，我们可以通过下面的流程图来看一看同步错误与异步错误在执行路径上的区别。

2. 问题复现：为什么你的代码失效了

假设你编写了一个组件，试图在 useEffect 或点击事件中发起异步请求并处理数据。如果请求失败，直接抛出错误，ErrorBoundary 将失效。

请看下面这段典型的错误代码：

// ErrorComponent.jsx
import React, { useEffect } from 'react';

function ErrorComponent() {
  useEffect(() => {
    // 模拟一个异步操作，例如 fetch 请求
    const timer = setTimeout(() => {
      try {
        // 这里发生了错误
        const data = JSON.parse('错误的 JSON 字符串');
      } catch (err) {
        // ❌ 错误直接抛出，此时 React 已经不在这个调用栈中
        throw err; 
      }
    }, 1000);

    return () => clearTimeout(timer);
  }, []);

  return <div>如果你看到我，说明还没报错</div>;
}

export default ErrorComponent;

在上述代码中，setTimeout 的回调函数是在浏览器的主线程事件队列中执行的，而非由 React 调度。当 throw err 执行时，React 已经无法通过 componentDidCatch 拦截它。这会导致应用直接崩溃，控制台报红，但外层的 ErrorBoundary 不会触发。

3. 解决方案：将异步错误转化为状态

既然 ErrorBoundary 无法捕获异步错误，我们就需要手动捕获这些错误，并将其转化为 React 能够处理的“状态更新”。当状态发生变化时，React 会重新渲染组件，此时如果我们在渲染逻辑中检查该状态并抛出错误（或者直接渲染错误 UI），ErrorBoundary 就能生效了。

执行以下步骤来修复代码：

1. 定义一个错误状态 error，初始值为 null。
2. 使用 try...catch 块包裹所有的异步逻辑。
3. 捕获到错误后，不要 throw，而是调用 setError(err) 将错误存入状态。
4. 在组件渲染的顶层检查 error 是否存在。如果存在，抛出这个错误，或者直接根据 error 渲染错误信息（推荐后者，或者为了复用 ErrorBoundary 而选择抛出）。

为了让你能够继续使用现有的 ErrorBoundary 组件，我们采用“捕获后更新状态，再次渲染时抛出”的策略。

修复后的代码如下：

// FixedComponent.jsx
import React, { useState, useEffect } from 'react';

function FixedComponent() {
  const [error, setError] = useState(null);

  useEffect(() => {
    const timer = setTimeout(() => {
      try {
        // 模拟可能出错的异步逻辑
        console.log('开始执行异步任务...');
        // 故意引发一个错误
        throw new Error('这是一个异步操作产生的错误');
      } catch (err) {
        // ✅ 关键点：不要直接 throw，而是更新 state
        setError(err);
      }
    }, 1000);

    return () => clearTimeout(timer);
  }, []);

  // ✅ 关键点：如果 error 状态存在，在渲染阶段抛出它
  // 此时 ErrorBoundary 就能捕获到这个错误了
  if (error) {
    throw error;
  }

  return <div>异步操作执行中...</div>;
}

export default FixedComponent;

4. 进阶封装：自定义 Hook

为了不每个组件都写一遍 try...catch 和 if (error) throw error，我们可以将这个逻辑封装成一个自定义 Hook。

创建一个名为 useAsyncError 的工具函数：

// useAsyncError.js
import { useState, useCallback } from 'react';

export const useAsyncError = () => {
  const [, setError] = useState();

  const catchError = useCallback((error) => {
    // 利用 setState 的回调机制，确保状态更新确实是 React 调度的
    setError(() => {
      throw error;
    });
  }, []);

  return catchError;
};

使用这个 Hook 可以极大简化代码：

// MyComponent.jsx
import React, { useEffect } from 'react';
import { useAsyncError } from './useAsyncError';

function MyComponent() {
  const throwAsyncError = useAsyncError();

  useEffect(() => {
    const fetchData = async () => {
      try {
        const res = await fetch('/api/wrong-url');
        if (!res.ok) throw new Error('请求失败');
      } catch (err) {
        // ✅ 直接调用 Hook 返回的函数，自动处理状态更新和抛出
        throwAsyncError(err);
      }
    };

    fetchData();
  }, [throwAsyncError]);

  return <div>正在加载数据...</div>;
}

export default MyComponent;

在这种模式下，throwAsyncError 内部通过 setState 触发了一次重新渲染。在重新渲染的过程中，setState 的回调函数执行了 throw error，这个抛出动作发生在 React 的渲染上下文中，因此被外层的 ErrorBoundary 完美捕获。

5. 处理未捕获的 Promise 拒绝

除了 async/await 和 setTimeout，未处理的 Promise 拒绝也是导致白屏的常见原因。你可以利用全局事件来兜底。

执行以下步骤在入口文件（如 index.js）中添加全局监听：

1. 监听 unhandledrejection 事件。
2. 阻止事件的默认行为（防止控制台报红）。
3. 将错误传递给一个全局的状态管理器（如果你使用 Redux 或 Context），或者直接更新根组件的状态来触发 ErrorBoundary。

// index.js
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

// 全局处理未捕获的 Promise 错误
window.addEventListener('unhandledrejection', (event) => {
  console.error('未处理的 Promise 拒绝:', event.reason);

  // 这里可以将 event.reason 传递给你的全局错误状态
  // 或者刷新页面、上报监控等
  // event.preventDefault(); // 如果想要阻止默认的控制台报错，取消注释此行
});

ReactDOM.render(<App />, document.getElementById('root'));

总结对比

为了方便记忆，我们将不同场景下的处理方式整理如下：

只要记住核心原则：ErrorBoundary 只管渲染时的事，异步的错误必须先变成 React 的状态，再交给它处理，就能彻底解决异步错误导致的白屏问题。