• 文档
• 技术博客
• 教程

本文基于《前端精读周刊》第 148 期精读内容整理扩充。Error Boundaries 是 React 16 引入的渲染错误捕获机制，本文从 API 用法、边界限制到与 Hooks、Function Component 的协作关系层层展开，并辅以周刊仓库内多篇相关精读作为佐证，帮助你彻底搞懂"什么时候能捕获、什么时候不能捕获、以及如何正确落地到生产项目"。

一、引言：为什么需要 Error Boundaries

在 React 16 之前，只要组件在渲染过程中抛出一个运行时错误，整个组件树就会从根节点卸载，页面直接白屏，而且控制台报错信息可读性极差，用户看到的是"什么都没有"的崩溃页面。

React 16.0 于 2017 年 9 月发布，首次引入了 Error Boundaries（错误边界），允许开发者把"渲染出错"降级为"展示一个可控的兜底 UI"，而不是整个应用崩溃。在 《React16 新特性》 的精读中对此有过明确描述：

React15 在渲染过程中遇到运行时的错误，会导致整个 React 组件的崩溃，而且错误信息不明确可读性差。React16 支持了更优雅的错误处理策略，如果一个错误是在组件的渲染或者生命周期方法中被抛出，整个组件结构就会从根节点中卸载，而不影响其他组件的渲染，可以利用 error boundaries 进行错误的优化处理。

一句话概括：Error Boundaries 是 React 提供的一种"局部异常隔离"能力，让出错组件之外的 UI 继续存活。

二、核心 API 与最小实现

Error Boundaries 的完整 API 定义如下（来自原精读的示例代码，可直接复制运行）：

class MyErrorBoundary extends Component { state = { error: null, }; static getDerivedStateFromError(error) { // 更新 state，下次渲染可以展示错误相关的 UI return { error: error }; } componentDidCatch(error, info) { // 错误上报 logErrorToMyService(error, info); } render() { if (this.state.error) { // 渲染出错时的 UI return <p>Something broke</p>; } return this.props.children; } }

两个生命周期方法各司其职：

判定规则：只要类组件定义了这两种方法中的任意一种，它就会成为 Error Boundary 组件，从而阻止子组件渲染时报错导致整棵组件树崩溃。

这里有个容易被忽略的点：getDerivedStateFromError是静态方法，无法访问this，所以它只能"改状态"，不能"做上报"；而componentDidCatch是实例方法，适合放置上报等副作用逻辑。二者配合使用是最标准的姿势——前者负责让 UI 切换到 fallback，后者负责把错误送进监控系统。

从版本脉络看，这两个 API 并非一次到齐：《React16 新特性》 中记录了 v16.0 时只有componentDidCatch，直到React 16.6才引入static getDerivedStateFromError()，其定位是"允许开发者在 render 完成之前渲染 Fallback UI"。也就是说：

• v16.0：componentDidCatch(error, info)+setState({ hasError: true })手动切换状态；
• v16.6+：推荐getDerivedStateFromError直接返回新 state，渲染阶段即可完成 fallback 切换，比在componentDidCatch里调用setState更贴合渲染阶段语义。

React Conf 2019 的分享中（见 《React Conf 2019 - Day2》）还提到一个迁移细节：官方提供了react-codemod中的error-boundaries迁移脚本，专门把早期unstable_handleError写法一键替换为componentDidCatch，方便老项目平滑升级。

组件拆分建议

原作者特别强调：建议将 Error Boundary 单独封装成一个独立组件，不要将错误监听方法与业务组件耦合。理由有二：

1. 复用性：错误兜底 UI（如"页面出错了，请刷新重试"）是通用能力，独立成组件后可以包在任何需要保护的子树外层；
2. 作用范围：错误检测只对子组件生效，如果写在业务组件自身里，它捕获不到自己渲染时抛出的错误，等于形同虚设。

// 全局通用的 ErrorBoundary，独立封装 class ErrorBoundary extends React.Component { // ...上面的两个生命周期方法 render() { if (this.state.error) { return <ErrorFallback error={this.state.error} />; } return this.props.children; } } // 使用：任意页面/模块外包一层即可 <ErrorBoundary> <UserProfile userId={id} /> </ErrorBoundary>

三、无法被捕获的四种官方场景

React 官方文档明确指出，有四类错误 Error Boundaries无法捕获，这也是开发者最容易踩坑的地方：

1. 事件回调（event handlers）中的错误。回调事件的执行时机不在渲染周期内，React 的 Error Boundary 只拦截"渲染期"错误，因此事件回调里抛错无法被 Catch，如有必要得自行try/catch；
2. 异步代码中的错误。比如setTimeout、requestAnimationFrame回调里抛错，和第一条同理——它们都不在 React 的渲染流程里；
3. 服务端渲染（SSR）时抛出的错误；
4. Error Boundary 组件自身触发的错误。因为它只能捕获其子组件的错误，自己抛错时没有上层边界兜底（除非再套一层）。

这四点有一个共同本质：Error Boundaries 的捕获范围严格限定在"渲染周期内、子组件抛出"的错误。离开这个范围，React 就管不着了。

编译时错误同样无能为力

除了官方列出的四种场景，结合自身经验还可以补充一类：编译时错误。

很明显，即便是 React 官方 API，Error Boundary 也只能捕获运行时错误，对编译时错误无能为力。编译时错误包括但不限于：

• 编译环境错误（webpack / babel / vite 编译失败）；
• 运行前的框架错误检查提示；
• TS / Flow 类型错误。

这些错误没有任何办法在运行时 Catch 住，遇到编译错误就在编译阶段解决，运行时只需要关注运行时错误即可。

四、两个高频误区澄清：Function Component 与 Hooks

误区一：函数式组件不能用 Error Boundaries？

函数式组件确实无法定义 Error Boundary（因为没有类组件的生命周期方法），但Error Boundary 完全可以捕获函数式子组件的错误，因此可以"曲线救国"：

// ErrorBoundary 组件（类组件） class ErrorBoundary extends React.Component { // ... } // 可以捕获所有组件异常，包括 Function Component 的子组件 const App = () => { return ( <ErrorBoundary> <Child /> </ErrorBoundary> ); };

App本身是函数组件，但它把Child包在类组件ErrorBoundary里，Child无论是函数组件还是类组件，渲染出错都会被捕获。所以实践中"函数组件项目"和"Error Boundaries 能力"并不冲突——只要有一层类组件边界即可。

误区二：Error Boundaries 对 Hooks 不生效？

Hooks 中的异常同样可以被 Error Boundaries 捕获。看下面这段代码：

const Child = (props) => { React.useEffect(() => { console.log(1); props.a.b; // 这里会抛错 console.log(2); }, [props.a.b]); return <div />; };

注意：当错误出现在useEffect的deps（依赖数组）中时，依赖计算发生在渲染阶段，错误会立即被 Catch，导致console.log(1)都无法打印。

而如果把依赖数组清空，让错误发生在 effect 执行体内，行为就完全不同：

const Child = (props) => { React.useEffect(() => { console.log(1); props.a.b; // 这里会抛错 console.log(2); }, []); // 依赖数组为空 return <div />; };

这种写法可以打印出console.log(1)，但无法打印出console.log(2)——effect 执行一半抛错，错误被外层 Error Boundary 捕获。

所以 React 官网这句话的真正含义需要仔细辨析：

componentDidCatch and getDerivedStateFromError: There are no Hook equivalents for these methods yet, but they will be added soon.

这句话不是说 Error Boundary 对 Hooks 不生效，而是说目前还没有与这两个方法等价的 Hooks 形态（你无法用useXxx的形式声明一个边界），对功能本身没有影响。周刊仓库中 《怎么用 React Hooks 造轮子》 也印证了这一结论：

对于getSnapshotBeforeUpdate,getDerivedStateFromError,componentDidCatch目前 Hooks 是无法模拟的。

也就是说：边界声明必须用类组件，但边界覆盖范围包含函数组件及其 Hooks 内抛出的渲染期错误。

五、Error Boundaries 与全局错误监控的配合

Error Boundaries 是**组件级（UI 局部）**的错误兜底方案，它解决的是"渲染崩溃降级"问题，但一个成熟产品还需要"全局监控"能力来发现和修复根因。在 《捕获所有异步 error》 的精读中，对二者的分工有清晰描述：

在具体的前端框架中，也可以通过框架提供的错误监听方案解决部分问题，比如 React 的 Error Boundaries、Vue 的 error handler，一个是 UI 组件级别的，一个是全局的。

全局异常监控一般通过两个浏览器 API 兜底：

• window.addEventListener('error')：监听所有同步、异步的运行时错误（但无法监听语法错误、接口错误、资源加载错误）；
• window.addEventListener('unhandledrejection')：监听 Promise 中抛出且未被.catch捕获的错误。

推荐的生产组合是：Error Boundaries 负责"UI 降级"，componentDidCatch内上报错误 + 全局error/unhandledrejection监听负责"不留死角"。这样即使错误发生在 Error Boundary 捕获不到的地方（如事件回调、异步任务、Promise 未处理 rejection），监控系统依然能第一时间收到告警。

六、原理层面的延伸理解

为什么渲染期错误可以被拦截？

Error Boundaries 之所以能工作，本质上是 React 在 Fiber 渲染流程中为每个子树"注册"了错误处理器：当子树的 render 或生命周期函数抛出异常时，React 会沿着组件树向上查找最近的 Error Boundary，找到后调用其getDerivedStateFromError/componentDidCatch并切换渲染路径。这与 JavaScript 的try/catch语义类似，但作用域被限定在"React 渲染周期"内。

值得注意的是，《Suspense 改变开发方式》 中揭示了一个更高级的用法：Suspense 的数据请求机制同样依赖componentDidCatch捕获"抛出的 Promise"，从而实现"用同步写法表达异步取数、渲染被暂停直到数据就绪"。这说明**"捕获异常 → 改变渲染路径"这套机制在 React 里是一等公民**，Error Boundaries 只是其中一个面向错误的应用场景。

与 React 16 版本演进的对应关系

其中 Fiber 架构把更新分为可中断的Reconciliation Phase（render 阶段）与不可中断的Commit Phase（提交阶段），Error Boundary 的捕获机制正是构建在这套渲染流程之上的。相关背景可参考 《React16 新特性》。

七、总结

最后把核心结论梳理成一张速查表：

Error Boundary可以捕获所有子元素渲染时异常，包括 render、各生命周期函数，但也有很多使用限制，希望你可以正确使用它。

错误捕获也不是万能的，更多时候我们要避免并及时修复错误，通过错误捕获降低出错时对用户体验的影响，并在第一时间内监控起来并快速修复。正确姿势是：边界负责降级体验，监控负责发现根因，双管齐下才是一个健壮前端应用该有的错误治理体系。

• 文档
• 技术博客
• 教程