企业官网建设流程全解析

线上最怕遇到的就是这种事故：某个页面在用户手机上突然白屏，后台日志里躺着一行“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 之外的事件也要区分处理。资源加载错误不会冒泡，需要在捕获阶段监听才能真正拿到。

下面这张表可以帮大家快速建立分类意识：

建立这个分类意识之后，后面每类错误的处理方案才有针对性。

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（服务端故障）、特定业务码（如资源不存在）分别映射到前端对应的处理策略：

错误处理的最终目的是给用户一个合理的反馈，并在后台留下可追踪的线索，而不是把所有异常都变成一串英文报错堆在控制台里。

6.3 React 19 的新变化：错误边界开始接管异步错误

聊几个新版本值得留意的点。React 19 对错误边界的能力做了增强，异步渲染场景下的一些错误现在可以被错误边界捕获了。具体来说，类似 async action、Transition 期间触发的异步执行发生在 React 的可中断渲染体系中，错误会被传播到最近的错误边界，而不是像以前那样变成野生 unhandledrejection。

这对依赖 useTransition、action 这类新特性的项目是个好消息，错误处理可以依托 React 自身机制做到更集中。但注意，这不是说普通事件处理器里的异步错误都能被边界捕获，职责边界并没有消失，只是 React 管理的异步场景有了更明确的归属。

如果你用的还是 React 18 及以下版本，上面提到的大部分实践完全适用，不用为了这个特性急着升级。

最后分享一点个人体会。我维护过的项目经历过从“只有一层全局 Error Boundary”到“分层边界 + 统一事件处理 + 全局兜底上报”的完整演变，最大的感受是：错误处理不是一个“写几个 try/catch”的即时任务，而是一套前期就要设计好的系统，而且要在每个错误处理点都刻意问自己一个问题——这句话谁能兜住？兜不住怎么办？这类问题想清楚了，线上白屏这种事就会越来越少。

现在再让我去处理那种线上诡异的报错，我不会再一头扎进代码里瞎猜，而是先翻监控里这个错误在哪个层级被捕获的、上报的组件栈指向哪里、当时的用户上下文是什么。有了分层兜底体系，大部分错误在到达用户之前就已经被拦截、降级、并留下线索了，这就是错误处理系统最大的价值。