uni.onError必须在App.vue的onLaunch中注册,用于捕获App端同步JS异常(如生命周期throw、API参数错误),不捕获模板渲染错误;uni.onUnhandledRejection同理注册,捕获未catch的Promise拒绝,二者均不可延迟或异步注册。

uni.onError 必须在 App.vue 的 onLaunch 中注册
App 端(iOS/Android)不走标准浏览器事件流,window.onerror 在这里基本无效,真正起作用的只有 uni.onError。它能捕获同步错误:比如生命周期钩子中 throw new Error()、uni.setStorageSync 参数非法、uni.navigateTo 传参错误等。
但注意:uni.onError 不捕获组件模板渲染错误(如访问 undefined.name),也不捕获 Vue 的响应式异常;它只管 JS 执行层抛出的同步异常。
- 必须写在
App.vue的onLaunch里,不能写在mounted、页面onLoad或任何异步回调之后 - 不要在
onLaunch里加await或网络请求逻辑,否则冷启动阶段的异常会直接丢失 - 推荐把处理函数抽成独立模块,例如
import { initGlobalError } from '@/utils/error',然后在onLaunch中直接调用initGlobalError()
uni.onUnhandledRejection 捕未 catch 的 Promise 拒绝
uni.onUnhandledRejection 是 App 端捕获未处理 Promise 拒绝的唯一可靠方式,覆盖 async/await 中漏掉 try/catch、Promise.reject() 后没接 .catch() 等场景。
它和 uni.onError 一样,必须在 App.vue 的 onLaunch 中注册;它不捕获已被 catch 的拒绝,也不捕获被 Promise.allSettled 吞掉的错误。
- 常见误判:把网络请求超时当成“未处理拒绝”——实际应由请求封装层统一拦截并转为业务错误,而非依赖全局兜底
- 不要在多个地方重复注册,否则可能触发多次上报或干扰 loading 锁逻辑
- 如果用了
uni-app-error-handler这类插件,确认它底层是否已帮你注册了这两个监听,避免重复绑定
Vue 模板错误和组件级异常无法靠 uni.onError 捕获
组件内模板报错(如 {{ user.profile.name }} 中 user 为 undefined)、v-for key 重复、指令语法错误等,uni.onError 和 uni.onUnhandledRejection 都收不到。App 端也用不了 Vue.config.errorHandler。
这类错误只能靠开发期 ESLint + TypeScript 类型检查提前暴露,或者在关键组件中手动加 try/catch 包裹 render 函数(不推荐,侵入性强)。
- H5 端可配合
Vue.config.errorHandler补充捕获,但 App 端无效,切勿混用 - 不要指望全局监听兜住所有错误——模板错误必须从源头控制,比如确保
user至少是空对象,或用可选链{{ user?.profile?.name }} - 真要监控这类问题,得靠灰度发布 + 用户行为埋点反推(比如某页面白屏率突增,再结合 sourcemap 定位可疑模板节点)
原生崩溃(闪退)完全不在 JS 异常捕获范围内
uni.onError 和 uni.onUnhandledRejection 只管 JS 层,对原生崩溃毫无感知。iOS 的 EXC_BAD_ACCESS、Android 的 NullPointerException、内存溢出、WebView 初始化失败等,JS 引擎根本没机会执行。
必须接入原生 SDK 才能采集,比如 Ba-Crash 插件或厂商提供的 crash 上报能力(如华为 HMS Crash Service)。
- 这类插件通常提供
crash.crash()方法监听闪退日志,支持本地缓存(路径类似Android/data/[包名]/files/crash_report.txt)和网络上报 - 别试图用 JS 层 reload 或重 launch 来“恢复”原生崩溃——它已经退出进程,JS 代码不再运行
- 上线前务必在真机上用插件的
test()方法模拟一次崩溃,验证日志能否正确生成并上报
onLaunch 同步执行,连 setTimeout 都不能有。


















