Vue 3 项目错误处理实战：Vue ErrorHandler、Promise 监控、用户友好提示

前言一个健壮的错误处理机制可以提升用户体验帮助开发者快速定位问题。今天分享如何实现完善的错误处理和监控错误分类错误类型 ├── Vue 渲染错误 │ ├── 组件渲染错误 │ ├── 生命周期钩子错误 │ └── 模板语法错误 ├── JavaScript 运行时错误 │ ├── TypeError │ ├── ReferenceError │ └── 自定义业务错误 ├── 异步错误 │ ├── Promise rejection │ ├── setTimeout/setInterval │ └── Web API 错误 └── 资源加载错误 ├── 图片加载失败 ├── 脚本加载失败 └── API 请求失败核心实现1. 全局错误处理// src/utils/errorHandler.tsimport{isDev}from./env// 错误日志服务classErrorLogger{privatelogs:ErrorLog[][]privatemaxLogs100log(error:Error,context?:string){constlog:ErrorLog{id:err_${Date.now()},message:error.message,stack:error.stack,context,timestamp:Date.now(),userAgent:navigator.userAgent,url:window.location.href}this.logs.unshift(log)// 只保留最近 N 条if(this.logs.lengththis.maxLogs){this.logsthis.logs.slice(0,this.maxLogs)}// 开发环境输出到控制台if(isDev){console.error([Error],context,error)}// 上报到服务器生产环境if(!isDev){this.reportToServer(log)}}privateasyncreportToServer(log:ErrorLog){// 可以发送到你的日志服务try{awaitfetch(/api/error-report,{method:POST,headers:{Content-Type:application/json},body:JSON.stringify(log)})}catch(e){// 存储到 localStorage 作为后备this.saveToLocalStorage(log)}}privatesaveToLocalStorage(log:ErrorLog){constkeyerror_logsconstexistingJSON.parse(localStorage.getItem(key)||[])existing.push(log)localStorage.setItem(key,JSON.stringify(existing.slice(-50)))}getLogs():ErrorLog[]{returnthis.logs}}interfaceErrorLog{id:stringmessage:stringstack?:stringcontext?:stringtimestamp:numberuserAgent:stringurl:string}exportconsterrorLoggernewErrorLogger()2. Vue 错误处理器// src/main.tsimport{createApp}fromvueimportAppfrom./App.vueimport{errorLogger}from/utils/errorHandlerconstappcreateApp(App)// Vue 渲染错误处理app.config.errorHandler(err,instance,info){// err: 错误对象// instance: 发生错误的组件实例// info: 额外的错误信息如生命周期钩子名称console.error(Vue Error:,err)console.error(Component:,instance)console.error(Info:,info)errorLogger.log(err,Vue Error [${info}])// 可以在这里显示用户友好的错误提示// showErrorToast(发生了一些问题请稍后重试)}// 组件警告处理开发环境if(import.meta.env.DEV){app.config.warnHandler(msg,instance,trace){console.warn(Vue Warn:,msg)console.warn(Trace:,trace)}}// 异步错误处理app.config.asyncErrorHandler(err,instance,info){errorLogger.log(err,Async Error [${info}])}app.mount(#app)3. Promise 错误处理// src/utils/promiseHandler.ts// 全局未处理的 Promise rejectionwindow.addEventListener(unhandledrejection,(event){console.error(Unhandled Promise Rejection:,event.reason)errorLogger.log(event.reasoninstanceofError?event.reason:newError(String(event.reason)),Unhandled Promise Rejection)// 阻止默认行为显示控制台错误event.preventDefault()})// 安全执行 PromiseexportasyncfunctionsafeAsyncT(promise:PromiseT,fallback?:T):PromiseT|undefined{try{returnawaitpromise}catch(error){errorLogger.log(errorinstanceofError?error:newError(String(error)),Safe Async)returnfallback}}// Promise 包装函数exportfunctiontoT(promise:PromiseT):Promise[Error|null,T|null]{returnpromise.then[null,T]((data)[null,data]).catch[Error,null]((err)[err,null])}4. API 请求错误处理// src/utils/request.tsimport{errorLogger}from./errorHandlerimport{ElMessage}fromelement-plusinterfaceRequestOptions{showError?:booleanerrorContext?:string}exportasyncfunctionrequestT(url:string,options:RequestOptions{}):PromiseT{const{showErrortrue,errorContextAPI Request}optionstry{constresponseawaitfetch(url)if(!response.ok){consterrornewError(HTTP${response.status}:${response.statusText})errorLogger.log(error,errorContext)if(showError){ElMessage.error(请求失败:${error.message})}throwerror}returnawaitresponse.json()}catch(error){if(errorinstanceofError){errorLogger.log(error,errorContext)if(showError!error.message.includes(HTTP)){ElMessage.error(网络请求失败请检查网络连接)}}throwerror}}// 使用示例asyncfunctionfetchArticle(id:string){returnrequestArticle(/api/articles/${id},{showError:true,errorContext:fetchArticle})}5. 资源加载错误处理// src/composables/useResourceError.tsimport{onMounted,onErrorCaptured}fromvueexportfunctionuseResourceError(){// 图片加载失败functionhandleImageError(event:Event){constimgevent.targetasHTMLImageElement img.src/default-image.png// 默认图片img.classList.add(error-loaded)}// 脚本加载失败functionloadScript(src:string):Promisevoid{returnnewPromise((resolve,reject){constscriptdocument.createElement(script)script.srcsrc script.onload()resolve()script.onerror(){reject(newError(Failed to load script:${src}))}document.head.appendChild(script)})}// Vue 组件内错误捕获onErrorCaptured((err,instance,info){console.error(Captured in component:,err)console.error(Component:,instance)console.error(Info:,info)// 返回 false 阻止错误继续传播returnfalse})return{handleImageError,loadScript}}6. 错误边界组件!-- src/components/ErrorBoundary.vue -- template slot v-if!hasError / div v-else classerror-boundary div classerror-content div classerror-icon/div h2页面出现了一些问题/h2 p别担心这只是一个小插曲/p div classerror-actions el-button typeprimary clickhandleRetry 重试一下 /el-button el-button clickhandleGoHome 返回首页 /el-button /div details v-ifshowDetails classerror-details summary查看错误详情/summary pre{{ errorMessage }}/pre /details /div /div /template script setup langts import { ref, onErrorCaptured } from vue import { useRouter } from vue-router const router useRouter() const hasError ref(false) const errorMessage ref() const showDetails ref(false) onErrorCaptured((err, instance, info) { hasError.value true errorMessage.value ${err.message}\n\nComponent: ${instance?.$options?.name || Unknown}\nInfo: ${info} console.error(ErrorBoundary caught:, err) // 返回 false 阻止错误传播 return false }) function handleRetry() { hasError.value false errorMessage.value } function handleGoHome() { hasError.value false router.push(/) } /script style scoped .error-boundary { display: flex; align-items: center; justify-content: center; min-height: 400px; padding: 40px; } .error-content { text-align: center; max-width: 400px; } .error-icon { font-size: 64px; margin-bottom: 20px; } .error-content h2 { margin: 0 0 8px; font-size: 24px; } .error-content p { color: #666; margin-bottom: 24px; } .error-actions { display: flex; gap: 12px; justify-content: center; margin-bottom: 24px; } .error-details { text-align: left; margin-top: 20px; } .error-details pre { background: #f5f5f5; padding: 16px; border-radius: 8px; overflow-x: auto; font-size: 12px; } /style7. 使用 ErrorBoundary!-- src/App.vue -- template ErrorBoundary router-view / /ErrorBoundary /template script setup langts import ErrorBoundary from /components/ErrorBoundary.vue /script错误监控服务推荐工具Sentry- 功能强大的错误追踪服务FunDebug- 国产前端监控工具Badjs- 腾讯开源的前端监控Sentry 集成npminstallsentry/vue sentry/tracing// src/utils/sentry.tsimport*asSentryfromsentry/vueimport{BrowserTracing}fromsentry/tracingexportfunctioninitSentry(app:any){Sentry.init({app,dsn:YOUR_SENTRY_DSN,integrations:[newBrowserTracing({routingInstrumentation:Sentry.vueRouterInstrumentation(router),}),],environment:import.meta.env.MODE,beforeSend(event){// 过滤非关键错误if(event.exception?.values?.[0]?.typeAbortError){returnnull}returnevent}})}最佳实践始终在 Promise 后添加 .catch()使用 try-catch 包装异步代码提供用户友好的错误提示记录详细错误日志便于调试相关资源Sentrysentry.ioFunDebugfundebug.com