React / 系统课时

错误边界与降级界面

错误边界与降级界面

本课解决组件渲染异常导致整棵 React 界面被卸载的问题。你将实现一个可复用错误边界,在子树失败时展示降级界面,并通过重新挂载完成重试。

学习目标

  • 理解错误边界能够捕获和不能捕获的异常范围
  • 使用类组件实现错误捕获、反馈与降级界面
  • 通过重置边界验证恢复流程

错误边界解决什么问题

React 渲染阶段出现未处理异常时,受影响的组件树可能无法继续生成可靠界面。错误边界把高风险子树包裹起来,在捕获异常后改为渲染备用内容,避免局部故障扩散到整个页面。

错误边界由类组件实现。getDerivedStateFromError 用于更新降级状态,componentDidCatch 用于记录错误和组件栈。它不会自动修复业务错误,而是提供隔离、反馈和恢复入口。

错误边界捕获与降级流程

实现错误边界与重试

下面示例包含可复用错误边界和故障演示页面。错误发生后,边界显示原因;点击“重新加载组件”会增加 boundaryKey,React 因 key 变化而创建新的边界实例。

tsx
// src/ErrorBoundary.tsx
import {
  Component,
  type ErrorInfo,
  type ReactNode,
} from "react";

type Props = {
  children: ReactNode;
  fallback: (error: Error) => ReactNode;
  onError?: (error: Error, info: ErrorInfo) => void;
};

type State = {
  error: Error | null;
};

export class ErrorBoundary extends Component<Props, State> {
  state: State = { error: null };

  static getDerivedStateFromError(error: Error): State {
    // 下一次渲染切换到降级界面
    return { error };
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    // 这里可接入日志或监控服务
    this.props.onError?.(error, info);
  }

  render() {
    if (this.state.error) {
      return this.props.fallback(this.state.error);
    }

    return this.props.children;
  }
}

// src/App.tsx
import { useState } from "react";
import { ErrorBoundary } from "./ErrorBoundary";

function UnstablePanel({ shouldFail }: { shouldFail: boolean }) {
  if (shouldFail) {
    throw new Error("报表组件渲染失败");
  }

  return <p>报表组件运行正常</p>;
}

export default function App() {
  const [shouldFail, setShouldFail] = useState(false);
  const [boundaryKey, setBoundaryKey] = useState(0);

  function retry() {
    setShouldFail(false);
    setBoundaryKey((value) => value + 1);
  }

  return (
    <main>
      <button onClick={() => setShouldFail(true)}>触发错误</button>

      <ErrorBoundary
        key={boundaryKey}
        onError={(error, info) => {
          console.error(error.message, info.componentStack);
        }}
        fallback={(error) => (
          <section role="alert">
            <p>当前模块暂时不可用:{error.message}</p>
            <button onClick={retry}>重新加载组件</button>
          </section>
        )}
      >
        <UnstablePanel shouldFail={shouldFail} />
      </ErrorBoundary>
    </main>
  );
}

预期结果

text
初始页面:报表组件运行正常
点击“触发错误”:显示“当前模块暂时不可用:报表组件渲染失败”
点击“重新加载组件”:恢复显示“报表组件运行正常”
控制台:记录错误消息和组件栈

开发模式下 React 还可能输出额外错误提示,具体格式会随开发工具和版本变化。

捕获范围与常见误区

错误边界能捕获其子组件在构造函数、生命周期和渲染期间抛出的异常,但不能捕获边界自身的错误。边界应放在可能失败区域的父级,而不是放在区域内部。

它也不能直接捕获事件处理函数、setTimeout、普通 Promise 回调或服务端渲染中的异常。这些位置应使用 try...catch、Promise 错误处理或框架提供的服务端错误机制。

懒加载模块下载失败会在渲染过程中以异常形式暴露,因此常见组合是:外层错误边界负责失败降级,内层 Suspense 负责加载占位。两者职责不同,不能互相替代。

降级界面设计原则

降级界面至少应说明哪个区域不可用,并提供与场景匹配的下一步,例如重试、返回上一页或提交反馈。不要直接向普通用户展示完整堆栈、文件路径或内部接口信息。

日志上报应包含错误消息、组件栈、当前路由和追踪标识,但要避免发送令牌、密码或用户隐私。重试按钮也应限制在可恢复场景;若数据写入状态不明确,应先重新查询状态,而不是盲目重复提交。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

错误边界与降级界面

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通