react-error-handling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Error Handling

React错误处理

Overview

概述

Error boundaries catch JavaScript errors during rendering, in lifecycle methods, and in constructors of child components. They display fallback UIs instead of crashing the entire component tree. Error boundaries can only be implemented as class components in vanilla React, but the

react-error-boundary

library provides a convenient function component wrapper.

When to use: Component crashes, preventing error propagation to parent routes, graceful degradation, user-facing error states, error logging and monitoring.

When NOT to use: Event handler errors (use try/catch), async callbacks outside rendering (setTimeout, promises without Suspense), server-side rendering errors, errors in the boundary itself.

错误边界会捕获子组件在渲染、生命周期方法以及构造函数中抛出的JavaScript错误，并显示备用UI，而非导致整个组件树崩溃。在原生React中，错误边界只能以类组件的形式实现，但

react-error-boundary

库提供了便捷的函数组件封装。

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

不适用场景： 事件处理器错误（使用try/catch）、渲染外的异步回调（setTimeout、未结合Suspense的promises）、服务端渲染错误、错误边界自身的错误。

Quick Reference

快速参考

Pattern	API	Key Points
Class boundary	`getDerivedStateFromError` + `componentDidCatch`	Manual implementation, full control
Function boundary	`<ErrorBoundary FallbackComponent={...} />`	Uses react-error-boundary library
Reset mechanism	`resetErrorBoundary()` or `resetKeys={[dep]}`	Auto-reset on state change or manual retry
Error logging	`onError={(error, info) => log(error)}`	Log to analytics or monitoring service
Fallback component	`FallbackComponent={MyFallback}`	Receives error and resetErrorBoundary
Inline fallback	`fallback={<div>Error occurred</div>}`	Static JSX, no error details
Render prop fallback	`fallbackRender={({ error, reset }) => <UI />}`	Dynamic fallback with error access
Nested boundaries	Wrap at multiple tree levels	Granular error isolation
Route-level boundary	TanStack Router `errorComponent`	Delegate to tanstack-router skill
Suspense integration	Wrap Suspense boundaries for async errors	Catch errors thrown by Suspense
Event handler errors	`try/catch` in handler, not error boundary	Boundaries don't catch event errors
useErrorBoundary hook	`const { showBoundary, resetBoundary } = useErrorBoundary`	Manually trigger boundary from child

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

Common Mistakes

常见误区

Mistake	Correct Pattern
Using error boundary for events	Use try/catch in event handlers
Wrapping every single component	Place boundaries at meaningful UI sections
Not providing reset mechanism	Include retry button or resetKeys
Showing stack traces in prod	Only render stack in development mode
Missing onError for logging	Always log errors to monitoring service
Catching errors in boundary self	Error boundaries only catch child component errors
Using async code in getDerived	getDerivedStateFromError must be pure, use didCatch
Relying on componentDidCatch	Use getDerivedStateFromError for state updates
Not testing error boundaries	Test with error-throwing components
Ignoring resetKeys pattern	Use resetKeys for automatic recovery on state change
Blocking Suspense fallbacks	Error boundaries around Suspense should allow fallbacks

错误做法	正确方案
为事件处理器使用错误边界	在事件处理器中使用try/catch
包裹每个单独组件	在有意义的UI区块设置错误边界
未提供重置机制	添加重试按钮或使用resetKeys参数
生产环境展示堆栈跟踪	仅在开发模式下渲染堆栈信息
缺失用于日志的onError回调	始终将错误记录至监控服务
捕获错误边界自身的错误	错误边界仅能捕获子组件的错误
在getDerivedStateFromError中使用异步代码	getDerivedStateFromError必须是纯函数，使用componentDidCatch处理异步逻辑
仅依赖componentDidCatch	使用getDerivedStateFromError更新状态
未测试错误边界	使用抛出错误的组件进行测试
忽略resetKeys模式	使用resetKeys实现状态变化时的自动恢复
阻塞Suspense备用界面	Suspense外层的错误边界应允许备用界面展示

Delegation

职责委托

If the
tanstack-router
skill is available, delegate route-level error handling (errorComponent, notFoundComponent, loader errors) to it. Otherwise, recommend:
npx skills add oakoss/agent-skills --skill tanstack-router

Error monitoring setup: Delegate to integration/observability specialists
Complex recovery flows: Use
```
Task
```
agent for multi-step error recovery patterns
Error boundary testing: Delegate test writing to testing specialists

如果
tanstack-router
技能可用，将路由级错误处理（errorComponent、notFoundComponent、加载器错误）委托给它。否则，推荐执行：
npx skills add oakoss/agent-skills --skill tanstack-router

错误监控设置：委托给集成/可观测性专家
复杂恢复流程：使用
```
Task
```
agent处理多步骤错误恢复模式
错误边界测试：委托给测试专家

References

参考资料

Class-based error boundaries
react-error-boundary library
Fallback UI patterns
Reset and recovery patterns
Error boundary placement strategies

类组件错误边界
react-error-boundary库
备用UI模式
重置与恢复模式
错误边界部署策略