React / 系统课时
错误边界与降级界面
错误边界与降级界面
本课解决组件渲染异常导致整棵 React 界面被卸载的问题。你将实现一个可复用错误边界,在子树失败时展示降级界面,并通过重新挂载完成重试。
学习目标
- 理解错误边界能够捕获和不能捕获的异常范围
- 使用类组件实现错误捕获、反馈与降级界面
- 通过重置边界验证恢复流程
错误边界解决什么问题
React 渲染阶段出现未处理异常时,受影响的组件树可能无法继续生成可靠界面。错误边界把高风险子树包裹起来,在捕获异常后改为渲染备用内容,避免局部故障扩散到整个页面。
错误边界由类组件实现。getDerivedStateFromError 用于更新降级状态,componentDidCatch 用于记录错误和组件栈。它不会自动修复业务错误,而是提供隔离、反馈和恢复入口。

实现错误边界与重试
下面示例包含可复用错误边界和故障演示页面。错误发生后,边界显示原因;点击“重新加载组件”会增加 boundaryKey,React 因 key 变化而创建新的边界实例。
// 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>
);
}预期结果
初始页面:报表组件运行正常
点击“触发错误”:显示“当前模块暂时不可用:报表组件渲染失败”
点击“重新加载组件”:恢复显示“报表组件运行正常”
控制台:记录错误消息和组件栈开发模式下 React 还可能输出额外错误提示,具体格式会随开发工具和版本变化。
捕获范围与常见误区
错误边界能捕获其子组件在构造函数、生命周期和渲染期间抛出的异常,但不能捕获边界自身的错误。边界应放在可能失败区域的父级,而不是放在区域内部。
它也不能直接捕获事件处理函数、setTimeout、普通 Promise 回调或服务端渲染中的异常。这些位置应使用 try...catch、Promise 错误处理或框架提供的服务端错误机制。
懒加载模块下载失败会在渲染过程中以异常形式暴露,因此常见组合是:外层错误边界负责失败降级,内层 Suspense 负责加载占位。两者职责不同,不能互相替代。
降级界面设计原则
降级界面至少应说明哪个区域不可用,并提供与场景匹配的下一步,例如重试、返回上一页或提交反馈。不要直接向普通用户展示完整堆栈、文件路径或内部接口信息。
日志上报应包含错误消息、组件栈、当前路由和追踪标识,但要避免发送令牌、密码或用户隐私。重试按钮也应限制在可恢复场景;若数据写入状态不明确,应先重新查询状态,而不是盲目重复提交。