线上最怕遇到的就是这种事故某个页面在用户手机上突然白屏后台日志里躺着一行“cannot read properties of undefined (reading name)”但根本定位不到是哪段代码出了问题。排查到凌晨发现是接口在某种极端场景下少返回了一个字段渲染组件直接抛错React 把整棵组件树都卸载了。事后复盘时大家都有一个共识我们对 React 错误处理的理解基本停留在“知道有 Error Boundary 这个东西”的层面完全没有形成一套体系化的兜底策略。这篇就来把 React 的错误处理彻底捋一遍。我会从错误类型的分类讲起到 Error Boundary 的原理和局限再到事件处理器、异步代码的兜底方案最后聊全局监控上报和一些实战里容易忽略的细节。适合正在负责 React 项目的开发者特别是经历过线上白屏、需要搭建前端错误监控体系的同学参考。1. 先盘清楚React 项目里的错误究竟分几类很多人以为“React 错误处理”就是包一层 try/catch 或者组件外面套一个 Error Boundary其实这是最大的误解。React 应用里的错误来源非常杂不同类型的错误在框架层面有不同的“命运”有些框架会主动捕获有些框架故意不碰有些框架根本感知不到。1.1 渲染阶段的错误框架能感知的错误这一类错误发生在 React 执行渲染流程的时候具体来说包括组件函数本身抛错函数组件体和类组件的 render 方法构造函数初始化时抛错生命周期方法里抛错比如 componentDidMount、componentDidUpdate、getDerivedStateFromProps 等setState 的 updater 函数抛错这些错误发生在 React 的“渲染事务”内部React 是感知得到的。React 的元素树渲染机制天然具备“错误边界”的捕捉能力当某个组件在渲染过程中抛出未捕获的异常时React 会向上遍历这棵组件树寻找最近的错误边界组件Error Boundary。如果找到了就用边界组件里定义的降级 UI 替换掉崩溃区域的渲染结果如果没找到极端情况下 React 会直接卸载整棵组件树页面就白屏了。这里特别提醒一个细节这里说的“渲染”不只是首次渲染也包括后续的每次 re-render。一个组件在首次渲染时好好的但某个 state 更新后 render 函数里访问了不存在的属性照样会抛错。这也是线上白屏最难排查的场景之一——首次加载正常用户交互一段时间后才触发。1.2 事件处理器里的错误框架故意不管的错误事件处理器也就是 onClick、onChange 这些回调React 在内部其实对它们做了事件委托但故意不捕获处理函数里抛出的错误。为什么故意不管因为 React 的设计哲学是事件处理器是一个“交互事务”的入口用户点击一个按钮函数执行到一半报错了这时候如果 React 介入并触发错误边界的降级 UI代价太重了——用户只是点击了一下整个局部页面却变成了“Something went wrong”体验反而更差。React 更希望你在事件处理器内部自己兜住错误弹个 toast、做个局部状态回滚都行而不是炸掉整棵组件树。所以事件处理器里的错误Error Boundary 是接不住的。你在边界组件的 componentDidCatch 里看到的错误信息里永远不会出现某个 onClick 里 throw 出来的异常。1.3 异步代码里的错误框架完全感知不到的错误Promise 回调、setTimeout、requestAnimationFrame、axios 请求的 .then/.catch、async 函数中 await 后面的代码这些异步任务执行时抛出的错误已经彻底离开了 React 的渲染调用栈。React 的执行环境从“渲染循环”切走之后错误走向完全由 JavaScript 运行时接管。Error Boundary 对这种错误无能为力它是 React 渲染栈内的保护机制不是 JavaScript 的全局异常捕获器。这也是很多团队犯的典型错误以为给路由外层包了一个 Error Boundary所有异步请求失败就都不怕了结果请求抛出异常依然会报 Uncaught (in promise) 错误边界组件完全无感知。1.4 资源加载与全局运行时错误最后一类是资源加载失败脚本、图片、样式表加载失败、非 React 控制的库抛出的运行时错误等。这些错误不仅 Error Boundary 管不了连 window.onerror 和 unhandledrejection 之外的事件也要区分处理。资源加载错误不会冒泡需要在捕获阶段监听才能真正拿到。下面这张表可以帮大家快速建立分类意识错误类型发生位置Error Boundary 能否捕获推荐兜底手段渲染阶段错误render、构造函数、生命周期能Error Boundary事件处理器错误onClick、onChange 等不能try/catch 统一错误处理函数异步错误Promise、setTimeout、async/await不能React 19 部分改善try/catch unhandledrejection资源加载错误script/img 等加载失败不能捕获阶段的 error 监听全局运行时错误未捕获异常不能window.onerror建立这个分类意识之后后面每类错误的处理方案才有针对性。2. 错误边界的机制与实现细节类组件为什么是唯一选择Error Boundary 从 React 16 开始引入是 React 渲染栈内唯一官方提供的错误捕获机制。它本质上是一个类组件因为只有类组件才有能力和时机去“截获”子树的渲染异常。2.1 错误边界的两个生命周期方法怎么分工Error Boundary 之所以必须是类组件是因为它需要借助类组件特有的生命周期方法static getDerivedStateFromError 和 componentDidCatch。先看一个最小实现import { Component } from react; class AppErrorBoundary extends Component { state { hasError: false, error: null }; static getDerivedStateFromError(error) { // 这里只能同步返回新的 state不能做任何副作用操作 // 比如 console.log、上报日志都不建议放这里 return { hasError: true, error }; } componentDidCatch(error, info) { // info.componentStack 里包含组件树的结构信息非常关键 // 上报逻辑放这里 // reportError(error, info); } render() { if (this.state.hasError) { return div页面开了个小差请刷新重试/div; } return this.props.children; } } export default AppErrorBoundary;这两个方法职责有明确分工static getDerivedStateFromError在渲染阶段调用React 需要在这个同步过程里拿到新的 state 以渲染降级 UI。因为处于渲染阶段它被要求是纯函数不能发起副作用操作。你在这里做上报会有风险——比如 React 在并发渲染下可能多次调用它导致重复上报。componentDidCatch在提交阶段调用此时 DOM 已经更新完成副作用可以安全执行。上报日志、记录错误详情、清理过期资源放这里都是合理的。我看到过不少团队把上报写在 getDerivedStateFromError 里理由是“这样一定能执行到”实际上正确的做法是放在 componentDidCatch 里。两者都会被调用时机不同用途也完全不同。2.2 错误边界为什么不捕获事件错误和异步错误这就要回到 React 的工作机制。Error Boundary 的实现原理本质上是 React 在调和reconciliation和提交commit阶段设置了一层“错误拦截点”。渲染阶段如果某个 fiber 节点处理时抛出异常React 会终止当前工作循环沿着 fiber 树向上寻找最近的错误边界进行恢复。但事件处理器和异步任务根本不在 React 的渲染工作循环里执行它们是独立的任务React 的错误拦截点自然拦截不到。官方文档也明确写了Error Boundary 无法捕获事件处理器、异步代码、服务端渲染和边界组件自身抛出的错误。理解了这一点你就不会再把 Error Boundary 当成“万能捕错网”了。它就是渲染树的保险丝不是 JavaScript 运行时的捕错器。2.3 错误边界的分层设计与状态重置实际项目中一个全局错误边界往往不够。线上白屏事故里最常见的情况是全局边界兜住了错误但降级 UI 永远停在那里用户点击“重试”也没反应因为边界组件的 hasError 状态一旦变成 true 就不会自动恢复。一个实用技巧是给边界组件加上 key 控制让 React 在用户点击重试时直接重新挂载边界内部的子树function BoundaryWrapper({ children, resetKey }) { return ( AppErrorBoundary key{resetKey} {children} /AppErrorBoundary ); }当 resetKey 变化时React 会卸载旧的子树创建一个全新的实例从而清空错误状态。这个 key 可以是当前路由 path、也可以是用户点击重试时递增的计数器。另一层设计是不要只放一个全局边界而是按照业务模块加局部边界。比如详情页、列表页、个人中心各自一个边界这样某个模块崩溃时其他模块依然可用。我的经验是全局边界负责兜底和上报局部边界负责“范围内降级”两者配合比单一全局边界体验好得多。3. 事件处理器里的错误别指望框架自己做兜底事件处理器是前端交互里最频繁触发错误的场所。用户每点一次按钮、每切换一个 tab背后都是一段事件处理逻辑。这段逻辑如果报错Error Boundary 管不了React 也不会帮你恢复错误会直接抛到全局环境。3.1 为什么框架故意不接管事件错误前文提过React 不捕获事件处理器错误是有意的设计选择。从用户体验角度也很好理解用户点击一个“提交”按钮如果处理器里报错最合理的反馈是按钮局部 loading 消失、弹出一个“提交失败请重试”的提示而不是整个页面变成降级 UI。React 团队在官方文档里说得也很直白错误边界的职责是“处理渲染期间的错误”事件错误应该由开发者自己处理。所以事件处理器里的错误处理本质上是JavaScript 的常规义务不是 React 的特殊问题。3.2 给事件处理器套一个统一错误处理工具纯靠每个业务函数里手写 try/catch维护成本高且容易漏。我更推荐封装一个统一的包裹函数让错误处理逻辑集中在同一个地方function withErrorHandler(handler, onError) { return async function (...args) { try { return await handler(...args); } catch (error) { onError?.(error); // 这里可以统一处理上报、弹提示、重置交互状态 return { ok: false, error }; } }; }使用的时候const handleSubmit withErrorHandler( async (values) { await submitForm(values); }, (error) { // 统一提示“提交失败” showToast(error.message || 提交失败了请稍后重试); // 上报到监控平台 reportError(error, { source: submit-form }); } ); // 在组件里直接使用 button onClick{handleSubmit}提交/button这个工具函数的好处是错误处理策略收敛到一个函数里后续要接监控平台、要加全局弹窗、要做错误采样只改一处就可以了。团队里新人也很难写错。3.3 局部降级不要让一次点击毁掉整个页面事件处理出错的另一个常见问题某个操作失败后组件内部状态可能处于“中间态”——比如 loading 还没关上、表单已提交的标记已经置位。这些状态污染不会自动消失会导致后续交互连环出错。我的实操建议是给每个“关键交互”设计独立的重置机制。最简单的方式是给表单组件一个 errorState失败时 setError 并关闭 loading复杂场景下可以把操作封装成一个自定义 hook内部用 reducer 管理 idle/pending/success/error 四种状态由错误处理器统一把状态机推进到 error。function useSubmission(submitFn) { const [state, setState] useState({ status: idle, error: null }); const run useCallback(async (...args) { setState({ status: pending, error: null }); try { await submitFn(...args); setState({ status: success, error: null }); } catch (error) { setState({ status: error, error }); } }, [submitFn]); return { run, ...state }; }这样用户点击“提交”即便接口报错组件只会切到错误状态不会让全局 UI 崩溃更不会留下 loading 卡死的后遗症。4. 异步错误处理Promise 与 async/await 的责任田异步错误是前端错误里占比最大的一部分尤其是依赖后端接口的页面。我统计过自己维护的项目线上运行时错误里超过六成来自异步回调。这类错误的主人是 JavaScript 运行时不是 React所以我们的方案也得更“原生”。4.1 异步错误为什么绕过了错误边界Promise 回调有自己的错误传播链。你用 await 接住一个 rejected Promise它会沿着 async 函数内部的调用栈一直走到最近的 try/catch如果没人接就会产生一个 unhandledrejection交给浏览器全局逻辑处理。这条链从头到尾都不经过 React 的渲染循环错误边界自然完全无知。需要注意的是即便你在 async 函数里 setState之后的状态更新触发的渲染错误依然会被边界捕获但 async 函数体本身的异常边界是接不住——这两件事经常被混淆。4.2 async/await 的可靠姿势对异步代码最可靠的处理方式还是 try/catch但要注意“哪里抛、哪里接”的边界。我的习惯是分层处理数据请求层统一封装请求函数把网络错误、HTTP 状态码异常、解析错误集中处理一次转换为业务可识别的错误信息。业务调用层只接自己关心的错误比如某个接口失败后要做特定的页面状态回滚。最外层兜底无论如何最终都要有捕获出口保证不产生 unhandledrejection。一个简单的请求封装示例async function request(url, options) { try { const res await fetch(url, options); if (!res.ok) { throw new Error(HTTP ${res.status}: ${url}); } return await res.json(); } catch (error) { // 统一上报网络错误和解析错误 reportError(error, { source: request, url }); // 经过统一处理后再向上抛给业务层 throw error; } }这里有个关键点catch 里不要吞异常。统一处理后如果你直接 return null 或者返回一个空对象业务层很容易在不知情的情况下走到“成功”的渲染分支最终渲染出错变成脏数据污染 UI。统一处理后还是要继续 throw让调用方明确知道“这次请求没有成功”。4.3 全局 unhandledrejection 兜底即使所有代码都写了 try/catch总会有漏网之鱼第三方库的内部实现、团队协作中某些同事忘记处理、旧代码里的历史遗留。所以全局监听不能省。window.addEventListener(unhandledrejection, (event) { const reason event.reason; const error reason instanceof Error ? reason : new Error(String(reason)); reportError(error, { source: unhandledrejection }); });要注意unhandledrejection 是一个兜底不是业务设计的一部分。如果某个页面的统治里大量出现这种兜底上报说明代码里“吞不干净”的问题已经相当严重还是要回头修业务代码。我见过一些团队把全局监听当成“万能方案”结果业务代码里的 try/catch 越写越少报错全依赖全局兜底这是本末倒置——全局兜底能保命但不能作为常态化设计。5. 全局兜底与监控上报前端最后一公里错误处理链条的最后一道防线是运行时全局监听和错误上报。即使错误边界、事件处理器、异步封装都做得很好依然可能出现框架管不住的场景某个第三方库在初始化时抛异常、页面加载阶段某个全局函数未定义、浏览器兼容性问题等。所以 window.onerror 和 unhandledrejection 这两道全局监听一定要挂上。5.1 window.onerror 只能兜底不能兜业务window.onerror 主要捕获未被任何 try/catch 处理的运行时异常包括语法错误之外的代码异常。但需要注意它捕获不到的常见场景包括Promise 内部的 rejection要用 unhandledrejection、资源加载错误要用捕获阶段监听、以及 async/await 中未被处理的异常这部分会进 unhandledrejection。资源加载错误是最容易被忽略的。图片加载失败、CDN 脚本加载失败这些 error 事件不会冒泡需要在捕获阶段监听window.addEventListener( error, (event) { const target event.target; if (target (target.tagName IMG || target.tagName SCRIPT || target.tagName LINK)) { reportError(new Error(resource load error), { source: resource, url: target.src || target.href, }); } }, true // 关键捕获阶段 );真实场景里很多“线上图片裂了但不知道是哪张”的问题就是靠这段代码发现的。5.2 上报信息的组织错误对象、组件栈、用户上下文上报到什么平台用什么通道每家团队都有自己的选择。但上报的数据结构是通用的。一份合格的错误上报信息至少应该包含错误对象本身message、stack、name浏览器版本和 OS 信息组件栈Error Boundary 的 componentDidCatch 能拿到 info.componentStack这是定位 React 组件层问题最关键的线索用户上下文用户所属的业务场景、当前路由、最近操作路径请求上下文最近几个接口的状态码、耗时很多错误在本地开发环境复现不出来就是因为缺少上下文。有一次我排查一个“列表偶发崩溃”的问题一直怀疑是并发数据问题后来通过上报数据里的 componentStack 定位才发现是某个组件内部根据一个枚举值渲染三级联动而后端在某个新场景下返回了枚举值之外的字符串导致数组越界读取。没有组件栈这个问题靠猜根本猜不到。5.3 上报去重和采样别把监控平台打爆上线错误监控的第一个月很容易被海量重复错误淹没。某个接口持续失败页面每个用户每次进入都会上报一次后台错误列表瞬间变成一堆完全一样的报错。我的做法是上报前先做去重。根据错误 message 和 componentStack 拼一个 key相同 key 的错误在短时间窗口内只报一次同时做哈希去重防止同一用户一次页面加载连续触发几十次同样的错误。const reportedKeys new Set(); function reportWithDeduplicate(error, context) { const key ${error.name}:${error.message}:${context.componentStack || }; if (reportedKeys.has(key)) return; reportedKeys.add(key); // 调用上报平台的 API }复杂系统里还要加上采样率。前端项目用户量级足够大时1% 的错误采样率已经能反映绝大多数问题没必要 100% 全量上报既保护监控平台的资源也避免自己公司流量费用浪费。5.4 开发模式和生产模式的差异最后提醒一个非常容易踩的坑开发模式和生产模式的错误堆栈完全是两个世界。React 在开发模式下会在错误表面加一层调试覆盖层展示组件树和源码位置方便定位但生产模式构建移除了这部分信息错误堆栈会被压缩。要想在生产环境拿到可读的堆栈信息需要在构建配置里开启 source map 上传并保证生产环境的 React 是压缩版本。很多团队只在本地调试时看过“漂亮”的错误堆栈上线后发现监控收到的全是 minified 代码晦涩的堆栈信息根本没法定位这就是前端工程化里特别容易被忽略的一环。6. 按项目规模设计一套错误处理体系从单页面到团队协作聊完各类错误的细节把这套东西落到真实项目里时会发现真正难的不是某个具体技术点而是“边界职责划分”——谁负责兜底、谁负责上报、谁负责恢复得先在架构层面想清楚。6.1 一层还是多层错误边界的层级设计项目规模小的时候一个全局错误边界就够用了。但项目复杂度上来之后页面里可能有多个独立的业务模块比如一个工作台页面同时包含通知列表、数据图表、快捷操作三个模块任何一个模块崩溃都不应该影响其他模块。这时候我推荐的分层方式全局级边界放在路由组件外层兜住整页级的异常展示整页降级 UI 并上报。模块级边界放在大业务区块外层区块崩溃时只替换该区块其他区块保持可用。组件级边界只针对高风险渲染区域使用比如复杂图表、长列表、富文本编辑器这类组件因为渲染逻辑复杂最容易出问题。合理的层级边界是 UI 完整性的保险丝它保证的是“一个区域坏了整个页面还能用”。6.2 与后端接口层错误码的统一前端错误处理如果只盯前端是远远不够的。我见过太多项目前端 try/catch 写得无比严密但一旦接口挂了页面报错信息还是“网络异常”这种用户看不懂的东西而实际上后端在响应体里返回了详细的业务错误码和错误文案。更务实的前后端对接方式是请求封装层统一解析接口的错误码体系把 401未登录、403无权限、5xx服务端故障、特定业务码如资源不存在分别映射到前端对应的处理策略场景前端处理策略401 未登录跳转登录页或弹出登录框403 无权限提示权限不足禁止重试429 限流提示稍后再试做退避重试5xx 服务端异常提示服务暂不可用自动重试一次业务错误码按业务文案展示不做全局兜底错误处理的最终目的是给用户一个合理的反馈并在后台留下可追踪的线索而不是把所有异常都变成一串英文报错堆在控制台里。6.3 React 19 的新变化错误边界开始接管异步错误聊几个新版本值得留意的点。React 19 对错误边界的能力做了增强异步渲染场景下的一些错误现在可以被错误边界捕获了。具体来说类似 async action、Transition 期间触发的异步执行发生在 React 的可中断渲染体系中错误会被传播到最近的错误边界而不是像以前那样变成野生 unhandledrejection。这对依赖 useTransition、action 这类新特性的项目是个好消息错误处理可以依托 React 自身机制做到更集中。但注意这不是说普通事件处理器里的异步错误都能被边界捕获职责边界并没有消失只是 React 管理的异步场景有了更明确的归属。如果你用的还是 React 18 及以下版本上面提到的大部分实践完全适用不用为了这个特性急着升级。最后分享一点个人体会。我维护过的项目经历过从“只有一层全局 Error Boundary”到“分层边界 统一事件处理 全局兜底上报”的完整演变最大的感受是错误处理不是一个“写几个 try/catch”的即时任务而是一套前期就要设计好的系统而且要在每个错误处理点都刻意问自己一个问题——这句话谁能兜住兜不住怎么办这类问题想清楚了线上白屏这种事就会越来越少。现在再让我去处理那种线上诡异的报错我不会再一头扎进代码里瞎猜而是先翻监控里这个错误在哪个层级被捕获的、上报的组件栈指向哪里、当时的用户上下文是什么。有了分层兜底体系大部分错误在到达用户之前就已经被拦截、降级、并留下线索了这就是错误处理系统最大的价值。