Vue 3 Composition API 异常处理与错误边界实现原理剖析

前言

在现代前端开发中，异常处理是构建稳定、可靠应用的关键环节。Vue 3 的 Composition API 为开发者提供了更灵活的组件逻辑组织方式，同时也带来了新的异常处理挑战。本文将深入探讨 Vue 3 Composition API 中的异常处理机制，包括错误边界组件实现、全局错误捕获、异步错误处理等高级特性，帮助开发者构建更加健壮的 Vue 应用。

Vue 3 异常处理基础概念

异常处理的重要性

在前端应用开发中，异常处理不仅仅是代码调试的工具，更是用户体验和系统稳定性的保障。Vue 3 作为现代前端框架，提供了丰富的异常处理机制来应对各种运行时错误。

Vue 3 异常处理机制概述

Vue 3 的异常处理机制基于以下几个核心概念：

1. 组件级异常捕获：每个组件都可以独立处理自己的异常
2. 全局异常捕获：在整个应用层面统一处理未被捕获的异常
3. 错误边界：类似 React 的错误边界概念，用于隔离组件中的错误
4. 异步错误处理：处理 Promise、定时器等异步操作中的异常

Composition API 中的错误处理

基础错误捕获

在 Composition API 中，开发者可以使用 try-catch 语句来捕获同步代码中的异常：

import { ref, onMounted } from 'vue'

export default {
  setup() {
    const data = ref(null)
    
    const fetchData = async () => {
      try {
        const response = await fetch('/api/data')
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`)
        }
        data.value = await response.json()
      } catch (error) {
        console.error('Failed to fetch data:', error)
        // 可以在这里处理错误，比如显示用户友好的错误信息
        handleError(error)
      }
    }
    
    const handleError = (error) => {
      // 统一错误处理逻辑
      if (error.message.includes('404')) {
        // 处理 404 错误
        console.warn('Resource not found')
      } else if (error.message.includes('500')) {
        // 处理服务器错误
        console.error('Server error occurred')
      }
    }
    
    onMounted(() => {
      fetchData()
    })
    
    return {
      data
    }
  }
}

使用 onErrorCaptured 钩子

虽然 Composition API 中没有直接的 errorCaptured 钩子，但可以通过 onErrorCaptured 来实现类似功能：

import { ref, onMounted, onErrorCaptured } from 'vue'

export default {
  setup() {
    const errorInfo = ref(null)
    const errorMessage = ref('')
    
    // 捕获子组件错误
    const handleChildError = (error, instance, info) => {
      console.error('Component error captured:', error)
      console.error('Component instance:', instance)
      console.error('Error info:', info)
      
      errorInfo.value = {
        error,
        instance,
        info,
        timestamp: new Date()
      }
      
      errorMessage.value = 'An error occurred in the component'
      
      // 返回 true 以阻止错误继续向上传播
      return true
    }
    
    onErrorCaptured(handleChildError)
    
    const triggerError = () => {
      throw new Error('This is a test error')
    }
    
    return {
      errorInfo,
      errorMessage,
      triggerError
    }
  }
}

全局错误处理机制

全局错误捕获配置

Vue 3 提供了 app.config.errorHandler 来设置全局错误处理器：

import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

// 全局错误处理器
app.config.errorHandler = (error, instance, info) => {
  console.error('Global error handler:', error)
  console.error('Component instance:', instance)
  console.error('Error info:', info)
  
  // 发送错误报告到监控系统
  if (process.env.NODE_ENV === 'production') {
    sendErrorReport({
      error: error.message,
      stack: error.stack,
      component: instance?.$options.name || 'Unknown',
      info,
      timestamp: new Date().toISOString()
    })
  }
}

// 全局未捕获异常处理器
window.addEventListener('unhandledrejection', (event) => {
  console.error('Unhandled promise rejection:', event.reason)
  
  if (process.env.NODE_ENV === 'production') {
    sendErrorReport({
      error: event.reason.message || 'Unhandled Promise Rejection',
      stack: event.reason.stack,
      component: 'Global',
      info: 'Unhandled Promise Rejection',
      timestamp: new Date().toISOString()
    })
  }
  
  // 阻止默认的错误处理
  event.preventDefault()
})

function sendErrorReport(report) {
  // 实际应用中这里会发送到错误监控服务
  console.log('Sending error report:', report)
  
  // 示例：发送到远程服务器
  /*
  fetch('/api/error-report', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(report)
  })
  */
}

app.mount('#app')

增强的全局错误处理

import { createApp } from 'vue'

const app = createApp(App)

// 增强版全局错误处理器
app.config.errorHandler = (error, instance, info) => {
  // 记录错误详情
  const errorDetails = {
    message: error.message,
    stack: error.stack,
    component: instance?.$options.name || 'Unknown',
    props: instance?.$props || {},
    info: info,
    timestamp: new Date().toISOString(),
    userAgent: navigator.userAgent,
    url: window.location.href
  }
  
  // 根据错误类型进行不同处理
  handleSpecificErrors(error, errorDetails)
  
  // 记录到本地存储用于调试
  localStorage.setItem('vue-error-log', JSON.stringify({
    ...errorDetails,
    timestamp: Date.now()
  }))
}

function handleSpecificErrors(error, details) {
  // 处理特定类型的错误
  if (error.message.includes('Network Error')) {
    showNetworkErrorNotification()
  } else if (error.message.includes('401')) {
    handleUnauthorizedAccess()
  } else if (error.message.includes('403')) {
    handleForbiddenAccess()
  }
  
  // 发送错误报告到监控系统
  reportToMonitoringService(details)
}

function showNetworkErrorNotification() {
  // 显示网络错误通知
  console.warn('Network error detected, please check your connection')
}

function handleUnauthorizedAccess() {
  // 处理未授权访问
  console.warn('Unauthorized access attempt')
  // 可以重定向到登录页面
  // window.location.href = '/login'
}

function handleForbiddenAccess() {
  // 处理访问被拒绝
  console.warn('Access forbidden')
}

function reportToMonitoringService(errorDetails) {
  // 实际的错误监控服务调用
  if (process.env.NODE_ENV === 'production') {
    // 这里可以集成 Sentry、LogRocket 等监控工具
    console.log('Reporting to monitoring service:', errorDetails)
  }
}

错误边界组件实现

基础错误边界组件

在 Vue 3 中，可以通过组合式 API 实现类似 React 错误边界的组件：

<template>
  <div class="error-boundary">
    <div v-if="hasError" class="error-container">
      <h3>Something went wrong</h3>
      <p>{{ error.message }}</p>
      <button @click="resetError">Try Again</button>
      <details v-if="error.stack">
        <summary>Details</summary>
        <pre>{{ error.stack }}</pre>
      </details>
    </div>
    <div v-else>
      <slot></slot>
    </div>
  </div>
</template>

<script>
import { ref, onErrorCaptured } from 'vue'

export default {
  name: 'ErrorBoundary',
  setup(props, { slots }) {
    const hasError = ref(false)
    const error = ref(null)
    
    const handleError = (err, instance, info) => {
      console.error('Error boundary caught:', err)
      error.value = err
      hasError.value = true
      
      // 可以在这里发送错误报告
      if (process.env.NODE_ENV === 'production') {
        sendErrorReport({
          error: err.message,
          stack: err.stack,
          component: instance?.$options.name || 'Unknown',
          info,
          timestamp: new Date().toISOString()
        })
      }
      
      // 阻止错误继续向上传播
      return true
    }
    
    const resetError = () => {
      hasError.value = false
      error.value = null
    }
    
    onErrorCaptured(handleError)
    
    return {
      hasError,
      error,
      resetError
    }
  }
}
</script>

<style scoped>
.error-container {
  padding: 20px;
  background-color: #ffebee;
  border: 1px solid #ffcdd2;
  border-radius: 4px;
  margin: 10px 0;
}

.error-container h3 {
  color: #c62828;
  margin-top: 0;
}

.error-container button {
  background-color: #c62828;
  color: white;
  border: none;
  padding: 8px 16px;
  border-radius: 4px;
  cursor: pointer;
  margin-top: 10px;
}

.error-container button:hover {
  background-color: #b71c1c;
}
</style>

高级错误边界组件

<template>
  <div class="advanced-error-boundary">
    <div v-if="showErrorDisplay" class="error-display">
      <div class="error-header">
        <h2>⚠️ Error Occurred</h2>
        <button @click="resetState" class="reset-btn">Reset</button>
      </div>
      
      <div class="error-content">
        <div class="error-message">{{ error.message }}</div>
        
        <div v-if="showErrorDetails" class="error-details">
          <h4>Technical Details</h4>
          <pre>{{ error.stack }}</pre>
        </div>
        
        <div class="error-actions">
          <button @click="copyError" class="action-btn">Copy Error</button>
          <button @click="reportError" class="action-btn">Report Issue</button>
        </div>
      </div>
      
      <div v-if="retryCount > 0" class="retry-info">
        <p>Retrying in {{ retryCount }} seconds...</p>
      </div>
    </div>
    
    <div v-else-if="showLoading" class="loading-container">
      <div class="spinner"></div>
      <p>Loading...</p>
    </div>
    
    <div v-else>
      <slot></slot>
    </div>
  </div>
</template>

<script>
import { ref, onErrorCaptured, onMounted } from 'vue'

export default {
  name: 'AdvancedErrorBoundary',
  props: {
    retryTimeout: {
      type: Number,
      default: 5000
    },
    showDetails: {
      type: Boolean,
      default: true
    }
  },
  setup(props, { slots }) {
    const hasError = ref(false)
    const error = ref(null)
    const showErrorDetails = ref(props.showDetails)
    const showLoading = ref(false)
    const retryCount = ref(0)
    
    let retryTimer = null
    
    const handleError = (err, instance, info) => {
      console.error('Advanced error boundary caught:', err)
      error.value = err
      hasError.value = true
      
      // 启动重试计时器
      startRetryTimer()
      
      return true
    }
    
    const startRetryTimer = () => {
      retryCount.value = Math.floor(props.retryTimeout / 1000)
      
      if (retryTimer) {
        clearInterval(retryTimer)
      }
      
      retryTimer = setInterval(() => {
        retryCount.value--
        if (retryCount.value <= 0) {
          clearInterval(retryTimer)
        }
      }, 1000)
    }
    
    const resetState = () => {
      hasError.value = false
      error.value = null
      retryCount.value = 0
      
      if (retryTimer) {
        clearInterval(retryTimer)
        retryTimer = null
      }
    }
    
    const copyError = () => {
      const errorText = `${error.value.message}\n${error.value.stack}`
      navigator.clipboard.writeText(errorText)
        .then(() => {
          console.log('Error copied to clipboard')
        })
        .catch(err => {
          console.error('Failed to copy error:', err)
        })
    }
    
    const reportError = () => {
      // 发送错误报告
      sendErrorReport({
        error: error.value.message,
        stack: error.value.stack,
        component: 'AdvancedErrorBoundary',
        info: 'User reported error',
        timestamp: new Date().toISOString(),
        userAgent: navigator.userAgent,
        url: window.location.href
      })
      
      alert('Error has been reported. Thank you for your feedback!')
    }
    
    onErrorCaptured(handleError)
    
    onMounted(() => {
      // 可以在这里添加一些初始化逻辑
      console.log('Advanced error boundary mounted')
    })
    
    return {
      hasError,
      error,
      showErrorDetails,
      showLoading,
      retryCount,
      resetState,
      copyError,
      reportError
    }
  }
}
</script>

<style scoped>
.advanced-error-boundary {
  position: relative;
}

.error-display {
  background-color: #fff3e0;
  border: 1px solid #ff9800;
  border-radius: 8px;
  padding: 20px;
  margin: 10px 0;
}

.error-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 15px;
}

.error-header h2 {
  color: #e65100;
  margin: 0;
}

.reset-btn {
  background-color: #ff9800;
  color: white;
  border: none;
  padding: 8px 16px;
  border-radius: 4px;
  cursor: pointer;
}

.reset-btn:hover {
  background-color: #f57c00;
}

.error-content {
  margin-bottom: 15px;
}

.error-message {
  color: #e65100;
  font-weight: bold;
  margin-bottom: 10px;
}

.error-details h4 {
  margin-top: 0;
  color: #ff9800;
}

.error-details pre {
  background-color: #fff8e1;
  padding: 10px;
  border-radius: 4px;
  overflow-x: auto;
  font-size: 12px;
}

.error-actions {
  display: flex;
  gap: 10px;
  margin-top: 15px;
}

.action-btn {
  background-color: #ff9800;
  color: white;
  border: none;
  padding: 8px 16px;
  border-radius: 4px;
  cursor: pointer;
  font-size: 14px;
}

.action-btn:hover {
  background-color: #f57c00;
}

.loading-container {
  text-align: center;
  padding: 20px;
}

.spinner {
  border: 4px solid #f3f3f3;
  border-top: 4px solid #ff9800;
  border-radius: 50%;
  width: 30px;
  height: 30px;
  animation: spin 1s linear infinite;
  margin: 0 auto 10px;
}

@keyframes spin {
  0% { transform: rotate(0deg); }
  100% { transform: rotate(360deg); }
}

.retry-info {
  text-align: center;
  color: #ff9800;
  font-weight: bold;
}
</style>

异步错误处理最佳实践

Promise 错误处理

import { ref, onMounted } from 'vue'

export default {
  setup() {
    const data = ref(null)
    const loading = ref(false)
    const error = ref(null)
    
    const fetchAsyncData = async () => {
      try {
        loading.value = true
        error.value = null
        
        // 模拟异步数据获取
        const response = await fetch('/api/data')
        
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`)
        }
        
        data.value = await response.json()
      } catch (err) {
        console.error('Fetch error:', err)
        error.value = err
        // 重新抛出错误让上层处理或记录
        throw err
      } finally {
        loading.value = false
      }
    }
    
    const handleAsyncError = (error, context) => {
      console.error(`Async error in ${context}:`, error)
      
      if (process.env.NODE_ENV === 'production') {
        // 生产环境发送错误报告
        sendErrorReport({
          error: error.message,
          stack: error.stack,
          context,
          timestamp: new Date().toISOString()
        })
      }
    }
    
    onMounted(() => {
      fetchAsyncData().catch(err => {
        handleAsyncError(err, 'fetchAsyncData')
      })
    })
    
    return {
      data,
      loading,
      error,
      fetchAsyncData
    }
  }
}

异步操作封装

import { ref } from 'vue'

// 创建异步操作工具函数
const useAsyncOperation = () => {
  const loading = ref(false)
  const error = ref(null)
  const data = ref(null)
  
  const execute = async (asyncFunction, ...args) => {
    try {
      loading.value = true
      error.value = null
      
      const result = await asyncFunction(...args)
      data.value = result
      
      return result
    } catch (err) {
      error.value = err
      console.error('Async operation failed:', err)
      
      // 在生产环境中报告错误
      if (process.env.NODE_ENV === 'production') {
        reportError(err, { operation: asyncFunction.name })
      }
      
      throw err
    } finally {
      loading.value = false
    }
  }
  
  const reset = () => {
    loading.value = false
    error.value = null
    data.value = null
  }
  
  return {
    loading,
    error,
    data,
    execute,
    reset
  }
}

// 在组件中使用
export default {
  setup() {
    const { loading, error, data, execute, reset } = useAsyncOperation()
    
    const fetchData = async () => {
      await execute(async () => {
        const response = await fetch('/api/users')
        if (!response.ok) {
          throw new Error(`Failed to fetch users: ${response.status}`)
        }
        return response.json()
      })
    }
    
    return {
      loading,
      error,
      data,
      fetchData,
      reset
    }
  }
}

定时器错误处理

import { ref, onUnmounted } from 'vue'

export default {
  setup() {
    const timerId = ref(null)
    const intervalId = ref(null)
    
    const startTimer = () => {
      try {
        // 清除之前的定时器
        if (timerId.value) {
          clearTimeout(timerId.value)
        }
        
        // 设置新的定时器
        timerId.value = setTimeout(() => {
          console.log('Timer executed successfully')
          // 这里可以处理定时任务的逻辑
        }, 5000)
      } catch (error) {
        console.error('Timer setup error:', error)
        handleError(error, 'startTimer')
      }
    }
    
    const startInterval = () => {
      try {
        if (intervalId.value) {
          clearInterval(intervalId.value)
        }
        
        intervalId.value = setInterval(() => {
          // 定期执行的任务
          console.log('Interval executed')
        }, 10000)
      } catch (error) {
        console.error('Interval setup error:', error)
        handleError(error, 'startInterval')
      }
    }
    
    const handleError = (error, context) => {
      console.error(`Error in ${context}:`, error)
      
      if (process.env.NODE_ENV === 'production') {
        sendErrorReport({
          error: error.message,
          stack: error.stack,
          context,
          timestamp: new Date().toISOString()
        })
      }
    }
    
    const cleanup = () => {
      if (timerId.value) {
        clearTimeout(timerId.value)
        timerId.value = null
      }
      
      if (intervalId.value) {
        clearInterval(intervalId.value)
        intervalId.value = null
      }
    }
    
    onUnmounted(() => {
      cleanup()
    })
    
    return {
      startTimer,
      startInterval
    }
  }
}

错误处理与用户体验优化

用户友好的错误显示

<template>
  <div class="user-friendly-error">
    <div v-if="errorType === 'network'" class="network-error">
      <div class="error-icon">📶</div>
      <h3>No Internet Connection</h3>
      <p>It seems you're not connected to the internet. Please check your connection and try again.</p>
      <button @click="retryAction" class="retry-btn">Retry Connection</button>
    </div>
    
    <div v-else-if="errorType === 'server'" class="server-error">
      <div class="error-icon">🖥️</div>
      <h3>Server Error</h3>
      <p>We're experiencing technical difficulties. Our team is working to fix the issue.</p>
      <button @click="contactSupport" class="support-btn">Contact Support</button>
    </div>
    
    <div v-else-if="errorType === 'data'" class="data-error">
      <div class="error-icon">📄</div>
      <h3>Data Error</h3>
      <p>There was an issue processing the requested data. Please try again later.</p>
      <button @click="refreshPage" class="refresh-btn">Refresh Page</button>
    </div>
    
    <div v-else class="generic-error">
      <div class="error-icon">⚠️</div>
      <h3>Something Went Wrong</h3>
      <p>We encountered an unexpected error. Please try again or contact support.</p>
      <div class="error-actions">
        <button @click="refreshPage" class="action-btn">Refresh</button>
        <button @click="contactSupport" class="action-btn">Contact Support</button>
      </div>
    </div>
  </div>
</template>

<script>
import { computed } from 'vue'

export default {
  name: 'UserFriendlyError',
  props: {
    error: {
      type: Error,
      required: true
    }
  },
  setup(props) {
    const errorType = computed(() => {
      if (props.error.message.includes('Network Error') || 
          props.error.message.includes('Failed to fetch')) {
        return 'network'
      } else if (props.error.message.includes('500') || 
                 props.error.message.includes('server')) {
        return 'server'
      } else if (props.error.message.includes('404') || 
                 props.error.message.includes('not found')) {
        return 'data'
      }
      return 'generic'
    })
    
    const retryAction = () => {
      // 重新尝试操作
      console.log('Retrying action...')
      window.location.reload()
    }
    
    const contactSupport = () => {
      // 联系支持团队
      console.log('Opening support contact...')
      // 可以打开支持页面或发送邮件
    }
    
    const refreshPage = () => {
      // 刷新页面
      window.location.reload()
    }
    
    return {
      errorType,
      retryAction,
      contactSupport,
      refreshPage
    }
  }
}
</script>

<style scoped>
.user-friendly-error {
  text-align: center;
  padding: 40px 20px;
}

.error-icon {
  font-size: 64px;
  margin-bottom: 20px;
}

.user-friendly-error h3 {
  color: #d32f2f;
  margin-bottom: 15px;
}

.user-friendly-error p {
  color: #757575;
  margin-bottom: 20px;
  line-height: 1.5;
}

.retry-btn, .support-btn, .refresh-btn, .action-btn {
  background-color: #d32f2f;
  color: white;
  border: none;
  padding: 12px 24px;
  border-radius: 4px;
  cursor: pointer;
  margin: 0 5px;
  font-size: 16px;
}

.retry-btn:hover, .support-btn:hover, .refresh-btn:hover, .action-btn:hover {
  background-color: #b71c1c;
}

.error-actions {
  margin-top: 20px;
}
</style>

错误恢复机制

import { ref, watch } from 'vue'

export default {
  setup() {
    const errorCount = ref(0)
    const lastErrorTime = ref(null)
    const canRetry = ref(false)
    
    const handleRecovery = (error) => {
      // 记录错误时间
      lastErrorTime.value = Date.now()
      
      // 增加错误计数
      errorCount.value++
      
      // 检查是否需要自动重试
      if (shouldAutoRetry()) {
        console.log('Attempting automatic retry...')
        // 可以在这里实现自动重试逻辑
      }
      
      // 更新重试状态
      updateRetryStatus()
    }
    
    const shouldAutoRetry = () => {
      // 如果最近5分钟内错误次数少于3次，允许自动重试
      if (!lastErrorTime.value) return true
      
      const timeDiff = Date.now() - lastErrorTime.value
      const fiveMinutes = 5 * 60 * 1000
      
      return errorCount.value < 3 && timeDiff < fiveMinutes
    }
    
    const updateRetryStatus = () => {
      // 设置重试状态，比如禁用某些功能
      canRetry.value = true
      
      // 30秒后重新启用
      setTimeout(() => {
        canRetry.value = false
      }, 30000)
    }
    
    const retryOperation = async (operation) => {
      try {
        return await operation()
      } catch (error) {
        handleRecovery(error)
        throw error
      }
    }
    
    // 监听错误计数变化
    watch(errorCount, (newCount, oldCount) => {
      if (newCount > 0) {