---
name: error-boundary
when: >-
  错误边界, 错误处理, 白屏, 页面崩溃, ErrorBoundary, 异常捕获, 全局错误, 前端异常, componentDidCatch,
  fallback
scope:
  - frontend
products:
  - '*'
id: ka-pattern-error-boundary
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 错误边界
  - 错误处理
  - 白屏
  - 页面崩溃
  - ErrorBoundary
  - 异常捕获
  - 全局错误
  - 前端异常
  - componentDidCatch
  - fallback
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- React 应用必须在路由级别包裹 ErrorBoundary，防止单个组件崩溃导致整个页面白屏
- 必须提供全局未捕获异常处理（window.onerror / window.addEventListener('error')）
- ErrorBoundary 的 fallback UI 必须包含：错误提示、重试按钮、返回首页链接
- 异步请求错误（网络、超时、服务端）统一在 axios 拦截器处理，禁止每个组件单独 try-catch
- Promise 未捕获 rejection 必须有全局监听（unhandledrejection event）
- 错误信息禁止暴露技术细节给用户（堆栈、SQL、内部 IP）
- 生产环境必须上报错误到监控服务（Sentry / 自建），禁止只在控制台打印
- loading / error / empty 三态必须完整处理，禁止只处理成功状态

## 验收项
- [AC-01] 路由级别有 ErrorBoundary 包裹
- [AC-02] fallback UI 有重试和返回首页
- [AC-03] 异步错误统一在拦截器处理
- [AC-04] loading/error/empty 三态完整
- [AC-05] 生产错误上报到监控服务
