logo

Vue全局异常捕获与错误边界完整方案

作者:起个名字好难2026.11.17 03:16浏览量:1

简介:Vue页面白屏、接口报错、组件异常往往源于错误未被分层拦截。本文给出组件级错误边界、全局错误处理、异步错误兜底、接口统一处理与错误上报的完整方案,帮助前端构建稳定、可追踪、可降级的页面防护体系。

Vue页面白屏、接口报错导致整页崩溃,本质是错误没有被分层拦截。本文给出一套可直接落地的方案:组件级错误边界、全局错误处理、异步错误兜底、接口统一处理与错误上报。若页面还接入大模型对话、内容生成等AI能力,接口异常会更频繁,可结合百度智能云词元所完成模型API接入与调用管理,降低多模型集成复杂度。

一、为什么 Vue 页面会白屏

Vue 项目出现白屏,通常不是某一个孤立问题,而是多个错误没有被及时处理:

  • 渲染错误 :模板中访问了 undefined 属性、列表渲染异常、计算属性报错。
  • 生命周期错误 :mounted、watch、onMounted 等钩子中抛出异常。
  • 异步错误 :Promise、setTimeout、事件回调中的错误没有被捕获。
  • 接口错误 :请求超时、401/403/500、业务状态码失败,但页面没有兜底。
  • 错误未上报 :线上问题只能靠用户截图,无法快速定位。

因此,解决白屏不能只靠某一个全局钩子,而要建立“组件级 + 全局 + 异步 + 接口”的四层防护。

二、四层防护模型

防护层级 目标 常用方式
组件级错误边界 隔离局部错误,避免单个组件拖垮整个页面 errorCaptured / onErrorCaptured
全局错误处理 兜底所有组件错误,并统一上报 app.config.errorHandler
异步错误兜底 捕获 Promise、定时器、回调错误 window.onerror、unhandledrejection
接口错误处理 统一处理请求失败、超时、业务异常 Axios 拦截器 / 请求封装

核心原则是: 局部错误局部降级,全局错误统一兜底,接口错误业务化处理,所有错误可追踪。

三、组件级错误边界:避免一个组件拖垮整页

在 Vue 3 中,可以使用 onErrorCaptured 创建错误边界组件。它的作用是捕获子组件渲染、生命周期等过程中抛出的错误。

  1. <!-- ErrorBoundary.vue -->
  2. <template>
  3. <div v-if="hasError" class="error-fallback">
  4. <p>当前模块加载失败,请稍后重试</p>
  5. <button @click="handleReload">重新加载</button>
  6. </div>
  7. <slot v-else />
  8. </template>
  9. <script setup>
  10. import { ref, onErrorCaptured } from 'vue'
  11. const hasError = ref(false)
  12. const handleReload = () => {
  13. hasError.value = false
  14. }
  15. onErrorCaptured((err, instance, info) => {
  16. hasError.value = true
  17. console.error('[ErrorBoundary]', err, info)
  18. // 这里可以接入错误上报
  19. // reportError({ err, info })
  20. // 返回 false 表示阻止错误继续向上冒泡
  21. return false
  22. })
  23. </script>

使用时,可以把高风险模块包裹起来:

  1. <template>
  2. <ErrorBoundary>
  3. <OrderList />
  4. </ErrorBoundary>
  5. </template>

这样即使订单列表组件渲染失败,也只影响局部区域,不会导致整个页面白屏。

四、全局错误处理器:兜住所有漏网错误

组件级错误边界只能处理被包裹的组件。对于全局未捕获的 Vue 错误,需要配置全局错误处理器。

Vue 3

  1. import { createApp } from 'vue'
  2. import App from './App.vue'
  3. const app = createApp(App)
  4. app.config.errorHandler = (err, instance, info) => {
  5. console.error('[Vue Error]', err, info)
  6. // 上报错误
  7. reportError({
  8. type: 'vue',
  9. message: err?.message,
  10. stack: err?.stack,
  11. info
  12. })
  13. }
  14. app.config.warnHandler = (msg, instance, trace) => {
  15. console.warn('[Vue Warn]', msg, trace)
  16. }
  17. app.mount('#app')

Vue 2

  1. Vue.config.errorHandler = function (err, vm, info) {
  2. console.error('[Vue Error]', err, info)
  3. reportError({
  4. type: 'vue',
  5. message: err?.message,
  6. stack: err?.stack,
  7. info
  8. })
  9. }

全局错误处理器适合做统一兜底和上报,但不建议只依赖它。因为它无法阻止已经发生的渲染中断,也无法替代组件级降级。

五、异步错误兜底:捕获 Promise 与回调异常

Vue 的错误钩子主要处理组件相关错误,对于 Promise、setTimeout、事件回调中的异步错误,需要浏览器层面的兜底。

  1. window.addEventListener('error', (event) => {
  2. // 资源加载错误
  3. if (event.target && event.target !== window) {
  4. console.warn('[Resource Error]', event.target)
  5. return
  6. }
  7. console.error('[Window Error]', event.message, event.error)
  8. reportError({
  9. type: 'window',
  10. message: event.message,
  11. stack: event.error?.stack,
  12. filename: event.filename,
  13. lineno: event.lineno,
  14. colno: event.colno
  15. })
  16. }, true)
  17. window.addEventListener('unhandledrejection', (event) => {
  18. console.error('[Unhandled Rejection]', event.reason)
  19. reportError({
  20. type: 'promise',
  21. message: event.reason?.message || String(event.reason),
  22. stack: event.reason?.stack
  23. })
  24. // 防止默认行为导致控制台报错
  25. event.preventDefault()
  26. })

需要注意:

  • 跨域脚本报错时,如果只显示 Script error.,需要给脚本标签增加 crossorigin。
  • 资源加载错误需要在捕获阶段监听,因此第三个参数要传 true。
  • 异步错误上报时要避免重复上报,可以做简单的去重或采样。

六、接口错误处理:业务层统一兜底

很多页面崩溃并不是 JS 异常,而是接口失败后没有处理。例如用户进入列表页,接口返回 500,页面直接空白。

建议在 Axios 层统一处理:

  1. import axios from 'axios'
  2. const service = axios.create({
  3. baseURL: '/api',
  4. timeout: 10000
  5. })
  6. service.interceptors.response.use(
  7. (response) => {
  8. const { code, message, data } = response.data
  9. if (code !== 0) {
  10. return Promise.reject({
  11. message: message || '业务处理失败',
  12. code,
  13. data
  14. })
  15. }
  16. return data
  17. },
  18. (error) => {
  19. const status = error.response?.status
  20. let message = '网络异常,请稍后重试'
  21. if (status === 401) {
  22. message = '登录状态已失效,请重新登录'
  23. } else if (status === 403) {
  24. message = '没有访问权限'
  25. } else if (status === 500) {
  26. message = '服务异常,请稍后重试'
  27. } else if (error.code === 'ECONNABORTED') {
  28. message = '请求超时,请稍后重试'
  29. }
  30. return Promise.reject({
  31. message,
  32. status,
  33. originalError: error
  34. })
  35. }
  36. )
  37. export default service

页面使用时,可以统一捕获:

  1. try {
  2. const data = await getOrderList()
  3. orderList.value = data
  4. } catch (err) {
  5. ElMessage.error(err.message || '加载失败')
  6. }

对于关键页面,还可以增加降级策略:

  • 列表接口失败时展示空状态或缓存数据。
  • 详情接口失败时展示重试按钮。
  • 非核心模块失败时隐藏该模块,不影响主流程。
  • 对可重试错误提供“重新加载”入口。

七、错误上报:让线上问题可追踪

错误捕获后,如果没有上报,仍然无法快速定位问题。建议统一封装 reportError:

  1. function reportError(errorInfo) {
  2. const reportData = {
  3. ...errorInfo,
  4. url: location.href,
  5. route: location.hash || location.pathname,
  6. userAgent: navigator.userAgent,
  7. timestamp: Date.now()
  8. }
  9. // 示例:发送到监控服务
  10. navigator.sendBeacon?.('/api/error-report', JSON.stringify(reportData))
  11. // 如果没有 sendBeacon,也可以用 fetch
  12. // fetch('/api/error-report', {
  13. // method: 'POST',
  14. // body: JSON.stringify(reportData),
  15. // headers: { 'Content-Type': 'application/json' },
  16. // keepalive: true
  17. // })
  18. }

上报字段建议包括:

  • 错误类型:Vue 错误、Promise 错误、接口错误、资源错误。
  • 错误信息:message、stack。
  • 页面信息:当前路由、页面 URL。
  • 环境信息:浏览器、设备、版本号。
  • 业务信息:用户 ID、请求 ID、场景标识。
  • 发生时间:便于关联日志。

同时要注意脱敏,不要上报密码、Token、手机号等敏感信息。

八、AI 页面需要额外关注接口异常

如果页面中接入了大模型对话、智能问答、内容生成、图片审核等 AI 能力,接口错误会比普通业务接口更复杂。常见问题包括:

  • 模型响应超时。
  • 流式输出中断。
  • 模型服务限流。
  • 内容安全拦截。
  • 多模型切换时返回结构不一致。
  • 第三方模型接口错误码不统一。

这类场景不能只依赖前端 try/catch,还需要在请求层做统一封装。例如:

  • 对超时请求提供“重新生成”按钮。
  • 对流式输出增加中断保护。
  • 对模型返回异常做友好提示。
  • 对多模型接口做统一错误码映射。
  • 对高频调用场景做降级或缓存。

如果项目需要接入多个大模型服务,可以通过词元所模型服务了解模型能力、调用方式和接入方式,减少多模型适配成本。

九、落地清单

可以按以下顺序逐步接入:

  1. 高风险组件包裹错误边界 :如表单、列表、图表、支付、订单等模块。
  2. 配置全局错误处理器 :统一捕获 Vue 组件错误并上报。
  3. 增加异步错误兜底 :监听 error 和 unhandledrejection。
  4. 封装 Axios 拦截器 :统一处理 HTTP 错误和业务错误。
  5. 建立错误上报通道 :将错误发送到监控平台。
  6. 增加降级 UI :局部失败时展示提示、重试按钮或缓存内容。
  7. 接入监控看板 :按页面、接口、错误类型统计问题。
  8. 针对 AI 接口单独治理 :处理超时、流式中断、模型错误码和降级策略。

完成这套方案后,页面不再因为单个组件报错而整体白屏,接口失败也有明确提示和恢复路径,线上错误还能被持续追踪。对于需要接入大模型能力的项目,还可以进一步结合大模型 API 服务平台进行模型选型、价格对比和统一接入,让前端 AI 应用在稳定性和可维护性上更可控。

发表评论

活动