Vue3 错误边界实战：手写可复用 ErrorBoundary，兜底线上崩溃

当你把 Vue3 学到第五阶段第78天，组合式 API、响应式原理、编译优化这些基本都摸透了，接下来真正拉开差距的其实是容错设计。界面可以做得复杂，但线上项目总得有人去兜底崩溃。这周我集中深挖了 Vue3 的错误边界机制，发现这块资料少、误区多，专门做了一次完整梳理和手写实践。这篇就是把第78天的核心收获整理成一份可以直接抄作业的实战笔记，从错误处理体系、onErrorCaptured 机制，到手写可复用的 ErrorBoundary 组件，再到全局错误监控和异步错误捕获，一条线讲透。适合已经能用 Vue3 独立开发组件、想在健壮性和线上稳定性上再进一步的同学参考。

1. 先搞清楚：Vue3 错误边界到底是个什么东西

1.1 相比 React，Vue 的错误边界为什么总被说成“没有”

很多从 React 转过来的同学，第一反应是找 Vue 官方的 ErrorBoundary，然后傻眼了：Vue3 文档里压根没有这个内置组件。于是社区里就流传一种说法，“Vue 没有错误边界”。这句话对，也不对。

React 的 ErrorBoundary 是一个类组件，通过componentDidCatch或者静态方法getDerivedStateFromError拦截子树渲染期间的错误，然后渲染 fallback UI。它的核心价值是把“一个组件崩溃”隔离成“一个局部 UI 降级”，而不是整棵组件树白屏。

Vue3 确实没有同名的内置边界组件，但提供了一套对等的底层能力：errorCaptured生命周期钩子、组合式 API 里的onErrorCaptured，以及应用级的app.config.errorHandler。官方文档叫它“错误传播”，说得很保守，但实际能力完全可以支撑起一个自定义 ErrorBoundary 组件。我自己在项目里实现了之后，效果不比 React 的差，甚至因为组合式 API 更灵活，能做的事情更多。

做一个不严谨但好理解的类比：React 的错误边界是开发商统一做好的防火门，你直接装就行；Vue3 没给你门，但给了你砖头、水泥和一份消防验收标准，你得自己砌。砌过一次之后，你会对整栋楼的防火分区更清楚。

所以要纠正一个认知：不是 Vue3 没有错误边界，而是 Vue3 把错误边界的“实现权”交给了开发者。用好了是利器，用不好就会出现“看起来捕获了，但线上还在白屏”的尴尬情况。

1.2 Vue3 错误处理体系的四个层级

在动手写边界组件之前，必须先把 Vue3 的错误处理层级图刻在脑子里。我把它分成四层，从内到外像洋葱一样：

这四层不是互斥的，而是会依次冒泡、逐级委托的。一个后代组件抛出错误，首先经过自身链路上的errorCaptured钩子，如果没有任何一级钩子返回false截停，错误就会继续向上冒，直到顶层的app.config.errorHandler。如果 Vue 应用层的处理也做完了，错误还能继续往浏览器原生window.onerror冒泡。

这个地方特别容易踩坑：很多人以为写了一个全局 errorHandler 就万事大吉，结果某个时刻页面还是崩了。原因通常是错误在某个组件的errorCaptured里被 return false 吞掉了，根本没到全局层。反过来也有问题，全局层处理了但不 return false，结果错误继续冒泡到 window.onerror，前端监控平台收到两条重复记录。

理解了这四个层级，你才能在设计错误边界的时候想清楚一件事：哪些错误要就地降级，哪些错误要放走上报，哪些错误要直接吞掉。这三个决策，才是错误边界设计的核心。

2. 核心机制拆解：onErrorCaptured 被很多人用错

2.1 钩子触发时机与冒泡规则

onErrorCaptured 的官方定义是：捕获来自后代组件的错误。这句话有两个关键词：“后代组件”和“捕获”。它不会捕获自身组件的错误，也不会捕获兄弟组件、父组件的错误，这点和 React 的 ErrorBoundary 行为一致。

错误冒泡规则有两条很关键：

第一，错误会从发生错误的组件开始，逐级向上通知祖先。假设组件结构是 A > B > C，C 渲染时报错，触发顺序是：B 的 errorCaptured → A 的 errorCaptured。B 处理完如果不截停，A 继续处理。

第二，如果某个errorCaptured钩子返回false，错误传播链路会被打断。上层的 errorCaptured、app.config.errorHandler 都不会再接收到这个错误。这就相当于你告诉 Vue：“我已经处理好了，别再上报了。”

实际业务中，我建议把“返回 false”当成一个需要主动决策的行为，而不是顺手写上去。因为一旦吞掉错误，排查时你连一条错误记录都看不到，只能看到一个毫无线索的降级 UI，这种问题最让人头疼。

2.2 为什么说返回 false 是边界设计的胜负手

我见过不少团队写的错误边界组件，长这样：

<script setup lang="ts"> import { ref, onErrorCaptured } from 'vue' const hasError = ref(false) onErrorCaptured(() => { hasError.value = true return false }) </script>

组件倒是简洁明了，但有两个隐患：

第一个隐患：错误被吞得干干净净。生产环境下没有 sourcemap 去还原 stack，没有错误详情，你只知道“某个东西坏了”，但哪个组件、哪个接口导致的，完全没有线索。尤其是多人协作的项目里，这种黑盒降级会让人想砸键盘。

第二个隐患：所有类型错误都被一刀切。有些后代组件错误其实是致命错误，就算局部降级了，主流程也无法继续（比如购物车核心逻辑挂了）。这时候正确的策略应该是降级 UI + 继续上报，也就是不返回 false，让它继续往上走，最后落到全局错误监控平台。

所以我的做法是：给 onErrorCaptured 留一个返回值决策位。捕获到错误之后，先判断错误是否具备“可恢复性”，再决定返回 true 还是 false。可恢复的定义因项目而异，比如一个图片轮播组件挂了，页面主体还在，属于可恢复；一个路由懒加载的模块挂了，页面内容直接缺失，不可恢复，必须让全局层知道。

这种区分思考，比“无脑 return false”要专业得多，也是把错误边界从“一个简单 try/catch 替代品”升级成“生产级容错方案”的关键。

3. 从零手写一个可复用的 ErrorBoundary 组件

3.1 组件设计目标与接口定义

理论基础准备好了，下面直接进入实操环节。我的设计目标很明确：写一个通用的 ErrorBoundary 组件，能包在任何业务组件外层，捕获到错误时展示降级界面，同时把错误信息回传给外部做上报。

接口设计如下：

• boundaryName：边界名称，用于埋在组件里时快速确认是哪个边界捕获了错误，上报和排查都好用。
• fallback：降级内容。支持两种形式：静态文案字符串，或者一个接收{ error, boundaryName, retry }对象的作用域插槽。静态省事、动态灵活。
• @error-captured：事件，外部可以监听这个事件实时感知边界触发，方便额外接日志上报逻辑。

另外一个容易被忽略的点：需要暴露一个retry方法，让降级 UI 有“重试”入口。因为很多错误是接口超时、偶发加载失败这类瞬时问题，给用户一个重试按钮，比让他们刷新整个页面体验好得多。

3.2 完整代码实现与分段解析

直接看核心实现，我用的是 Vue 3.2+ 的<script setup>组合式写法：

<template> <slot v-if="!hasError" /> <slot v-else name="fallback" :error="error" :boundary-name="boundaryName" :retry="retry"> <div class="error-boundary fallback"> <p>当前模块加载失败，请稍后重试</p> <button @click="retry">重试</button> </div> </slot> </template> <script setup lang="ts"> import { ref, onErrorCaptured, provide } from 'vue' defineOptions({ name: 'AppErrorBoundary' }) const props = defineProps({ boundaryName: { type: String, default: 'anonymous-boundary' } }) const emit = defineEmits<{ (e: 'error-captured', payload: { error: Error; boundaryName: string }): void }>() const hasError = ref(false) const error = ref<Error | null>(null) // 暴露给插槽或外部调用的重试方法 function retry() { hasError.value = false error.value = null } onErrorCaptured((err: Error) => { error.value = err hasError.value = true emit('error-captured', { error: err, boundaryName: props.boundaryName }) // 正常情况不返回 false，让错误继续向上冒泡到全局监控 return true }) </script>

逐段拆开说一下关键点：

• 核心状态就是hasError和error。前者管 UI 翻转，后者保存错误对象，供 fallback 插槽展示错误信息。
• retry方法做的事很朴素，重置两个状态。但有个细节：重置之后，插槽里的组件会重新挂载吗？答案是会的。因为hasError从 true 变成 false，原来的<slot />会重新渲染，而 Vue 的 diff 会重新创建之前卸载的组件树，错误边界天然支持重试，不需要额外做 key 管理。
• onErrorCaptured里没有返回 false，而是返回 true。原因上面分析过，要让错误继续冒泡到全局层，保证监控平台能收到这条错误。如果你的业务里确实需要局部吞掉，把这个返回值改成 false 就行。
• 用defineOptions声明组件 name，在 Vue 3.3+ 的<script setup>里是标准做法。如果项目还在 3.2，建议拆成普通defineComponent写法。

这个组件只负责捕获“渲染、生命周期、watcher”这三类错误。后面会提到，事件处理器和异步任务里的错误它是管不到的，界限要清楚。

3.3 用 provide/inject 把错误信息传给插槽内容？

写的时候有个需求：把错误详情塞给插槽内部的某个子组件，让 UI 可以直接展示 stack 或错误码。最直觉的做法是作用域插槽，也就是把 error 对象作为 slot props 传下去。这个方案没错，但它只能影响一层插槽结构。

如果错误信息需要下钻到插槽里再下钻两层的深层组件，层层传 props 会很啰嗦。我的处理是：在捕获错误的瞬间，通过provide把错误上下文抛出去，深层的任意组件都能随时inject到这份上下文，不用关心中间隔了几层。

// 在 onErrorCaptured 中补充 provide('boundary-context', { boundaryName: props.boundaryName, error: err })

深层组件里：

const boundaryCtx = inject('boundary-context')

这个技巧在复杂业务里特别实用，也是 Vue 组合式 API 相比 React 高阶组件方案的优势点。当然，过度用 provide/inject 会让数据流变模糊，我建议只在错误上下文这类“全局低频数据”上使用。

4. 实操集成：从局部兜底到全局监控

4.1 在 main.ts 接入全局错误采集

局部边界组件解决的是 UI 体验问题，但错误不能只烂在浏览器里。生产环境必须有全局统一采集的通道，我们的落地姿势是在main.ts里配置app.config.errorHandler：

import { createApp } from 'vue' import App from './App.vue' const app = createApp(App) app.config.errorHandler = (err, instance, info) => { // instance 是出错时所在的组件实例，info 是 Vue 附加的错误位置说明 console.error('全局错误捕获:', err) const payload = { message: err instanceof Error ? err.message : String(err), stack: err instanceof Error ? err.stack : '', componentName: instance?.type?.name ?? instance?.type?.__name ?? 'unknown', info, url: window.location.href, time: Date.now() } // 接入之前提到的错误上报 SDK，这里用伪代码示意 // reportError(payload) } app.mount('#app')

这里有个经验之谈：不要试图在 errorHandler 里重组出完整的组件链。instance 只是当前出错组件实例，你拿不到完整的父级链路。想要这个信息，就得配合业务侧的日志上下文，或者在每个边界组件上报时自己附加边界名。

另外，info 这个参数 Vue 会给一句类似error occurs in render function的提示，能帮判断错误来源是 render、setup 还是生命周期，排查时非常有用，一定要收集进去。

4.2 按路由页面与核心业务隔离边界的落法

边界组件写好了，不能只当花瓶。我的落地习惯是按以下三个粒度来包：

第一个粒度是路由页面级。在 router 的组件包装层，直接把页面组件包一层 ErrorBoundary。这样任何一个页面崩溃，也只是那个页面白屏/降级，导航栏、侧边栏、底部栏都还活着，用户至少还能点回首页。

<template> <AppErrorBoundary boundary-name="layout-main"> <RouterView /> </AppErrorBoundary> </template>

第二个粒度是核心业务卡片级。比如首页有十几个数据卡片，一个卡片接口挂掉不应该拖垮整个首页。按卡片粒度包边界，坏了哪个就降级哪个，剩下的卡片正常展示。这是错误边界最高价值的用法。

第三个粒度是动态组件/异步组件级。带defineAsyncComponent的异步模块，加载失败或者 chunk 加载失败时，默认行为很难看。包上边界之后，加载失败可以优雅降级，还能通过 retry 让用户手动重新拉取 chunk。

三个粒度按需组合，不需要在每一个小组件上都包边界，那样反而会让组件树变得臃肿。

4.3 异步错误与错误边界的二道防线

前面反复提到，onErrorCaptured 抓不到异步任务里的错误。举个例子：

setTimeout(() => { throw new Error('异步错误') }, 0)

这个错误既不会触发组件 errorCaptured，也不会触发 app.config.errorHandler，只会变成 window.onerror 事件。原因在于 Vue 的错误捕获机制只 wrap 了 render、watcher、生命周期钩子这几类同步调用链，异步任务根本不在钩子的调用栈里。

解决方案我总结为两层：

第一层，业务代码里主动包装异步函数。写一个统一工具：

function withAsyncError<T>(fn: () => Promise<T>, context?: string): Promise<T> { return fn().catch((err: Error) => { // 统一走全局错误通道，而不是让错误在 Promise 里悄悄消失 reportError({ error: err, context, source: 'async' }) throw err }) }

所有接口请求、定时器回调里尽量走这个包装，保证异步错误至少能落到上报平台。

第二层，在window.addEventListener('unhandledrejection')里兜底。万一有没被处理的 Promise 拒绝，也记录下来。这层兜底不要做 UI 降级，因为事件发生在任何组件上下文之外，你根本不知道对应哪个组件，做 UI 干预反而可能误伤用户操作。

两层配合下来，错误捕获覆盖率会明显提升，线上告警的准确性也会好很多。

5. 常见坑位与问题排查实录

5.1 错误边界不生效的四个高频原因

这段时间实操下来，我总结了错误边界不生效最常见的四个原因，如果你发现边界组件写了没用，按这个清单排查：

原因一：错误发生在边界组件自身

onErrorCaptured 只能捕获后代组件错误。如果你把 ErrorBoundary 和业务组件写在同一个组件里，然后业务组件报错，边界钩子是收不到的。解决方式是必须拆成父子结构，业务组件放在插槽/子组件里。

原因二：错误发生在事件回调中

点击事件、滚动事件这些原生事件回调里的报错，Vue 不会主动触发 errorCaptured。你只能在事件回调里自己 try/catch，或者在全局 window.onerror 层面兜底。边界组件对这类错误是无能为力的，这是框架机制决定的，不是代码写错了。

原因三：捕获到了错误但 return false 吞掉了

这是最隐蔽的“不生效”。错误其实在某个祖先组件的 errorCaptured 里被拦截了，然后祖先没做任何 UI 变化。看起来像边界没触发，实际是错误根本没冒泡到你写的边界。排查方法很简单：在所有 errorCaptured 钩子里的第一行打个 console.error，看错误到底停在哪一层。

原因四：异步队列里的错误根本没被 Vue 收集

Promise 回调、定时器、requestAnimationFrame 里的 throw，Vue 都收集不到。这个前面展开过，不赘述，重点是把全局 unhandledrejection 监听和统一异步包装函数用起来。

5.2 错误上报信息不够用怎么办

生产环境里的错误，最让人头疼的就是信息太少：一个几百行的缩混代码 stack，一个模糊的 “Cannot read properties of undefined”，根本不知道用户是在哪个页面、哪一步操作触发。

我的经验是，不要只依赖 Vue 的错误对象。在错误边界捕获和全局 errorHandler 里，主动补充四类上下文：

• 边界名/组件名：最小粒度定位在哪段 UI
• 路由信息：当时用户停留在哪个路由
• 操作步骤：如果业务侧有操作埋点，联动拉取最近几个事件
• 关键业务字段：比如订单号、商品 ID，方便直接拉日志关联

说白了，错误监控的价值不只是“知道系统出错了”，而是“知道哪里出错、用户干了什么导致出错”。这两者之间的差距，全靠附加上下文补。

5.3 边界组件自身也别“悄悄失败”

最后提一个容易被忽视的稳定性问题：边界组件本身也要写得足够保守。不要在 errorCaptured 回调里做复杂的逻辑，比如网络请求、大计算、DOM 操作。因为在“错误处理链路上”再抛出错误，会导致非常难排查的连环问题，甚至让 Vue 直接终止渲染。

我的硬性要求是：边界组件的捕获回调里只做三件纯操作——状态赋值、事件 emit、provide 上下文。其他一切尽可能后置到 nextTick 或者独立的错误处理服务里。

同时，错误信息展示的 fallback UI，也不能再依赖业务组件里的任何数据源，必须是一个完全不依赖外部状态的纯静态区域。否则降级界面本身也崩了，那用户体验就是灾难中的灾难。

写在最后的实战心得

几轮实践下来，我有一个越来越强烈的体会：错误边界不是“包一个组件就完事”的配置项，它是一套需要配合全局监控、异步错误治理、上下文增强共同作用的体系。单独把 ErrorBoundary 写得再漂亮，没有全局通道、没有异步兜底，覆蓋率也是残缺的。

现在我的标准动作是：新项目启动第一天就把边界组件和错误监控链路搭好，而不是等线上开始报警了才手忙脚乱地补。搭好之后，给自己一个“故障演练”的习惯——故意在某个组件里写一段会抛错的 mock 代码，验证边界是否如期降级、上报是否如期送达。这个小小的演练，往往能在关键时刻救你一命。