React错误边界（Error Boundary）备用UI、Fallback UI、getDerivedStateFromError、componentDidCatch、Suspense

开发中推荐使用react-error-boundary库来实现错误边界

什么是 React 错误边界（Error Boundary）

错误边界是 React 16+ 提供的一种组件机制，用于在组件树渲染阶段发生错误时，优雅地捕获并隔离错误，防止整个应用白屏，并展示备用 UI（Fallback UI）。它只影响其子树，不会向上“炸裂”。

• 可以捕获：子组件在渲染（render）、生命周期（如 componentDidMount）、构造函数中的错误。
• 无法捕获：
  • 事件处理函数中的错误（应使用 try/catch）
  • 异步回调（如 setTimeout、Promise.then）
  • 服务端渲染（SSR）中的错误
  • 自身组件内部抛出的错误（边界仅对“子树”生效）

---

核心 API 与工作原理

错误边界必须是一个 class 组件，并实现以下两个生命周期之一或全部：

• static getDerivedStateFromError(error)：同步更新 state，渲染备用 UI。
• componentDidCatch(error, errorInfo)：副作用场景，如打点上报、日志记录。

最小实现示例：

import React from 'react';

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    // 在这里上报：Sentry、Datadog、内部日志系统等
    console.error('ErrorBoundary caught an error:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback ?? <h2>出错了，请稍后重试。</h2>;
    }
    return this.props.children;
  }
}

export default ErrorBoundary;

使用方式：

<ErrorBoundary fallback={<div>模块加载失败</div>}>
  <ProblematicComponent />
</ErrorBoundary>

---

作用范围与边界划分建议

• 全局级：在 App 顶层包裹一次，兜底未知错误，避免白屏。
• 路由级/页面级：为每个路由页面放置错误边界，互不影响。
• 模块级/小部件级：对风险较高的区块（远程模块、富文本渲染、图表、3D、可插拔插件）设置边界，提升健壮性。
• 异步分片：对 React.lazy/动态 import 的边界配合 Suspense 放置，分别处理“加载中”和“加载失败”。

示例（页面与模块组合）：

<GlobalErrorBoundary fallback={<FullPageFallback />}>
  <Router>
    <Route
      path="/dashboard"
      element={
        <PageErrorBoundary fallback={<SectionFallback />}>
          <Dashboard />
        </PageErrorBoundary>
      }
    />
    <Route
      path="/editor"
      element={
        <PageErrorBoundary fallback={<SectionFallback />}>
          <Suspense fallback={<Loading />}>
            <LazyEditor />
          </Suspense>
        </PageErrorBoundary>
      }
    />
  </Router>
</GlobalErrorBoundary>

---

与 Suspense 的关系

• Suspense 处理的是“等待异步数据/代码”的状态（loading），不是错误。
• 对于 React.lazy 的加载失败（如网络错误），需要错误边界来展示“失败态”。
• 常见组合：
  • Suspense 提供加载中 UI
  • ErrorBoundary 提供失败 UI

---

Hook 时代如何优雅使用（react-error-boundary）

错误边界本质必须是 class 组件。函数组件可通过成熟库简化：

• react-error-boundary（推荐）
  • 提供 <ErrorBoundary>、useErrorHandler、resetKeys 等能力
  • 支持一键重试与重置

示例：

import { ErrorBoundary } from 'react-error-boundary';

function Fallback({ error, resetErrorBoundary }) {
  return (
    <div>
      <p>出错了：{error.message}</p>
      <button onClick={resetErrorBoundary}>重试</button>
    </div>
  );
}

function App() {
  const [version, setVersion] = React.useState(0);

  return (
    <ErrorBoundary
      FallbackComponent={Fallback}
      onError={(error, info) => {/* 上报 */}}
      onReset={() => setVersion(v => v + 1)}
      resetKeys={[version]} // 依赖变化自动重置错误状态
    >
      <RiskyWidget key={version} />
    </ErrorBoundary>
  );
}

---

无法捕获的错误与对应策略

- 事件处理函数：

• 使用 try/catch 包裹；必要时封装通用的 safeRun(() => ...)。

- 异步回调（Promise、setTimeout）：

• 在 Promise 链尾部 .catch(handleError)；
• 在 async/await 外围使用 try/catch；
• 对全局未处理异常，监听 window.onerror、window.onunhandledrejection 做兜底上报（仍然不由错误边界渲染 UI）。

- SSR：

• 在服务器端框架（如 Next.js）用框架内置的错误页（_error.js/error.js）和中间件处理；
• 客户端水合之后，错误边界才开始起效。

---

设计优质 Fallback UI 的要点

• 清晰可见：告诉用户“发生错误”，避免模糊空白。
• 可重试：提供“重试”按钮，重置边界状态（通过 key 或库的 resetErrorBoundary）。
• 降级方案：能否渲染简版内容或替代信息。
• 诊断支持：在开发环境展示错误信息；在生产隐藏细节但提供反馈渠道。
• 可观察性：在 componentDidCatch 或 onError 上报错误、用户上下文、版本信息等。

---

与路由/微前端/远程模块的实践

• 对于远程组件（Module Federation、Dynamic Import），必须在加载点外层放置错误边界。
• 微前端场景下，给每个子应用或 iframe 容器设置专属边界，避免跨子域影响。

---

在 Next.js、Remix 等框架中的使用

• Next.js 13+（App Router）有 error.js/global-error.js，可作为路由层面的错误边界；组件级错误仍可用自定义边界。
• Remix 有 ErrorBoundary 约定导出，作用于路由层。组件级同理可自定义错误边界。

---

测试与监控

• 使用 React Testing Library/Jest 模拟子组件抛错，断言 Fallback UI 是否渲染、上报是否被调用。
• 在监控平台（Sentry/Datadog/LogRocket）中关联用户操作、版本号、路由信息，便于回放与定位。

示例（测试思路伪码）：

test('渲染失败时展示替代 UI 并上报', () => {
  const report = jest.fn();
  const ui = render(
    <ErrorBoundary fallback={<div>Oops</div>} onError={report}>
      <Boom /> {/* render 中抛错 */}
    </ErrorBoundary>
  );
  expect(ui.getByText('Oops')).toBeInTheDocument();
  expect(report).toHaveBeenCalled();
});

---

常见坑与排查清单

• 以为能捕获所有错误：记住它只管“渲染阶段的子树错误”。
• 忘记重置：错误发生后边界会“卡住”，通过变更 key 或 resetKeys 重置。
• 边界自身报错：确保 Fallback UI 简单稳定，避免在 fallback 中再次抛错。
• 滥用顶层唯一边界：只放全局边界会让所有错误都走同一 UI，影响体验。分区更好。
• 与 Suspense 混用不当：加载中用 Suspense，失败用错误边界，职责分离。
• 未上报：componentDidCatch/onError 不做上报，问题难以排查。

---

推荐落地模板

• 顶层兜底（例如在 App）：

<ErrorBoundary fallback={<FullPageError />}>
  <AppRoutes />
</ErrorBoundary>

• 高风险模块边界：

<SectionErrorBoundary fallback={<CardError />}>
  <ChartsPanel />
</SectionErrorBoundary>

• 与 Suspense 组合：

<ErrorBoundary fallback={<LoadFailed />}>
  <Suspense fallback={<Spinner />}>
    <LazyModule />
  </Suspense>
</ErrorBoundary>

---

结语

错误边界是 React 在运行时可靠性上的关键机制。通过合理分层放置边界、设计良好的 Fallback UI、完善的错误上报与重置策略，你可以显著提升应用的稳定性与可维护性。配合 react-error-boundary 等库，你还能在函数组件栈中更轻松地实现可重试、可重置、可观测的错误处理体验。