react-error-handling

React 错误处理

概述

错误边界可以捕获渲染期间、生命周期方法中以及子组件构造函数中的 JavaScript 错误。它们会显示备用 UI，而不是让整个组件树崩溃。在原生 React 中，错误边界只能通过类组件实现，但 react-error-boundary 库提供了便捷的函数组件包装器。

适用场景： 组件崩溃、防止错误向上传播至父路由、优雅降级、面向用户的错误状态、错误日志记录与监控。

不适用场景： 事件处理程序中的错误（使用 try/catch）、渲染之外的异步回调（setTimeout、未使用 Suspense 的 Promise）、服务端渲染错误、错误边界自身发生的错误。

快速参考

模式	API	要点
类边界	getDerivedStateFromError + componentDidCatch	手动实现，完全掌控
函数边界	<ErrorBoundary FallbackComponent={...} />	使用 react-error-boundary 库
重置机制	resetErrorBoundary() 或 resetKeys={[dep]}	状态变化时自动重置，或手动重试
错误日志记录	onError={(error, info) => log(error)}	记录到分析或监控服务
备用组件	FallbackComponent={MyFallback}	接收错误和 resetErrorBoundary
内联备用 UI	fallback={<div>Error occurred</div>}	静态 JSX，不包含错误详情
渲染属性备用 UI	fallbackRender={({ error, reset }) => <UI />}	可访问错误的动态备用 UI
嵌套边界	在组件树的多个层级进行包装	精细隔离错误
路由级边界	TanStack Router errorComponent	委托给 tanstack-router 技能
Suspense 集成	包装 Suspense 边界以处理异步错误	捕获 Suspense 抛出的错误
事件处理程序错误	在处理程序中使用 try/catch，而不是错误边界	边界不会捕获事件错误
useErrorBoundary hook	const { showBoundary, resetBoundary } = useErrorBoundary	从子组件手动触发边界

常见错误

错误	正确做法
用错误边界处理事件	在事件处理程序中使用 try/catch
包装每一个组件	在有意义的 UI 区域放置边界
未提供重置机制	添加重试按钮或设置 resetKeys
在生产环境显示堆栈跟踪	仅在开发模式下渲染堆栈跟踪
未设置 onError 进行日志记录	始终将错误记录到监控服务
在边界自身中捕获错误	错误边界只能捕获子组件错误
在 getDerived 中使用异步代码	getDerivedStateFromError 必须是纯函数，应使用 didCatch
依赖 componentDidCatch	使用 getDerivedStateFromError 更新状态
未测试错误边界	使用会抛出错误的组件进行测试
忽略 resetKeys 模式	使用 resetKeys 在状态变化时自动恢复
阻止 Suspense 备用 UI	Suspense 周围的错误边界应允许显示备用 UI

委派

如果有 tanstack-router 技能，请将路由级错误处理（errorComponent、notFoundComponent、加载器错误）委派给它。否则，建议：npx skills add oakoss/agent-skills --skill tanstack-router

• 错误监控设置：委派给集成／可观测性专家
• 复杂恢复流程：使用 Task Agent 处理多步骤错误恢复模式
• 错误边界测试：委派测试专家编写测试

参考资料

• 基于类的错误边界
• react-error-boundary 库
• 备用 UI 模式
• 重置和恢复模式
• 错误边界放置策略