Skip to Content
🎉 Nextra 4.0 is released. dimaMachina is looking for a new job or consulting .
指引错误边界

什么是错误边界

错误边界 (Error Boundary) 是 React 提供的一种机制，用于捕获其子组件树中发生的运行时渲染错误，并防止整个应用崩溃。错误边界能展示一个回退 UI，以保证错误被捕获并可在一定程度上自动恢复或提示用户采取措施。

Note

本框架使用的两个错误边界

本框架中使用了两个层级的错误边界，分别用于全局捕捉和路由级捕捉：

  1. 全局错误边界
    • 使用 react-error-boundary 中的 <ErrorBoundary> 组件，在整个应用最外层包裹（见 main.tsx 或 main.jsx）。
    • 主要作用：在渲染入口捕捉所有子组件（包括路由、状态管理、UI 等）中出现的渲染错误，展示Fallback UI，避免应用整体崩溃。
    • 典型用法： 
      root.render(
  <ErrorBoundary fallbackRender={FallbackRender}>
    <Provider store={store}>
      <App />
    </Provider>
  </ErrorBoundary>
);
  2. 路由错误边界
    • React Router（V6.4+）自带的错误处理机制，也称为 Data Router Error Boundary 。
    • 主要作用：在页面或路由级捕捉错误，例如 loader/action 逻辑出错，或页面组件渲染出现异常时，可以就近使用路由的 error boundary（errorElement 或 error.tsx）来处理。
    • 这样在某些页面逻辑出错时，仅影响该页面，并不会波及整个应用。

如何使用与扩展

全局错误边界

在 main.tsx (或 main.jsx) 中，最外层使用 <ErrorBoundary> 包裹整个应用：

// main.tsx
 
import { ErrorBoundary } from 'react-error-boundary';
import FallbackRender from './components/ErrorBoundary.tsx';
 
root.render(
  <ErrorBoundary fallbackRender={FallbackRender}>
    <App />
  </ErrorBoundary>
);
  • fallbackRender 属性接受一个函数或组件，用于在捕获到错误时显示回退 UI。
  • 当整个应用出现任何不可预期的渲染错误时，就会渲染 FallbackRender 中的内容，而不会导致应用白屏或崩溃。

在 FallbackRender 里做些什么

示例（简化版）：

// components/ErrorBoundary.tsx
import type { FallbackProps } from 'react-error-boundary';
import { Button, Typography } from 'antd';
 
export default function FallbackRender({ error, resetErrorBoundary }: FallbackProps) {
  // 在这里可以做一些日志上报
  console.error('Caught by ErrorBoundary:', error);
 
  return (
    <div className="flex-center-col gap-2">
      <Typography.Text type="danger">{error.message}</Typography.Text>
      <Button onClick={resetErrorBoundary}>重试</Button>
    </div>
  );
}
  • error: 捕获的错误对象，可用来做日志上报、弹窗提示等。
  • resetErrorBoundary: 当调用该函数时，会尝试重新渲染出错组件树，若错误已解决，组件即可恢复正常。

路由错误边界

在 React Router 中，你可以在路由配置里设置 errorElement，或者在文件系统路由里新建 error.tsx，用于捕获当前路由或 loader 内发生的错误。示例：

// 伪代码示例
<Route
  path="/somePage"
  element={<SomePage />}
  errorElement={<PageError />}
/>

或者在文件系统路由中：

src/
 └─ pages/
     └─ somePage/
         ├─ page.tsx      // 正常页面组件
         └─ error.tsx     // 本页面的错误边界组件

这样，当 SomePage 或其 loader 出现错误时，会优先渲染 PageError 组件，而不会触发全局的 <ErrorBoundary>。

与全局边界的关系

当路由内的错误边界无法处理（例如路由本身未定义错误边界，或错误边界组件抛错），就会冒泡到更外层的全局 <ErrorBoundary>。因此，你可以在不同层级对错误进行分级处理：

  1. 路由级：针对某个页面、数据获取或其他局部逻辑所出现的错误，可以在这里做页面刷新、回退或显示具体信息。
  2. 全局级：当错误超出路由级能处理的范围，或根本没在路由中出现时，由全局边界捕捉并提供统一的回退 UI（如返回首页按钮、查看日志等）。

总结

  • 全局错误边界 (react-error-boundary + 自定义 FallbackRender)
    • 捕获根组件及其子组件树中的任何渲染错误，防止应用整体崩溃。
    • 你可以在 FallbackRender 中做错误信息展示、重试按钮、日志埋点等操作。
  • 路由错误边界 (React Router 自带)
    • 更“就近”的错误处理机制，可在特定页面/路由的 loader、action、渲染错误时触发，从而定制化地给出对应的错误提示或 UI 回退。
    • 若未定义或路由错误边界也出错，则会fallback到全局错误边界。

这样一来，你既可以对单个页面或特定路由进行细粒度的错误处理，也能在应用顶层提供一个通用的安全网。两者都通过相同或相似的错误展示组件（如 ErrorPage 或 FallbackRender）来渲染，开发者可在该组件里进行任何所需的错误处理、用户提示或监控上报等逻辑，从而让应用更健壮、更易调试。

Last updated on
使用国际化