路由守卫抛出错误怎么办？教你利用 onError 捕获全局跳转异常

路由守卫中抛出错误怎么办？教你利用 onError 捕获全局跳转异常

在Vue Router的开发中，你是否遇到过这样的场景：导航突然中断，页面一片空白，控制台却抛出一个令人困惑的错误？这背后，往往是路由守卫中的异常在作祟。好消息是，Vue Router提供了一个强大的全局钩子——onError，它能帮你统一捕获和处理这类跳转异常，有效防止应用因局部错误而彻底崩溃。

什么是路由守卫中的错误？

简单来说，当你在beforeEach、beforeEnter或组件内守卫（例如beforeRouteEnter）中执行逻辑时，如果同步抛出了一个错误（比如throw new Error(...)），或者一个异步操作（例如API调用）被拒绝（Promise.reject()），导航就会宣告失败。此时，Vue Router并不会自动消化这个错误，它会向上冒泡到全局，其结果就是阻塞后续的跳转流程，给用户带来糟糕的体验。

用 router.onError 捕获所有跳转异常

如何优雅地收拾这个“烂摊子”？答案就是router.onError()。你可以在创建路由实例之后，通过这个方法注册一个全局的错误处理器。一旦任何守卫在执行过程中抛出错误，这个处理器就会被调用，并接收到详细的错误对象。

• 注册时机是关键：务必在createRouter之后、app.use(router)之前完成注册，确保钩子生效。
• 错误对象解析：处理器接收到的错误通常包含标准的message和stack信息。更妙的是，你也可以抛出携带自定义属性的错误对象（例如throw { code: 'AUTH_REQUIRED' }），以便在处理器中进行更精细的判断。
• 核心应用场景：这个全局钩子的用武之地相当广泛，包括但不限于：将错误上报至监控系统、自动跳转到统一的错误页面、向用户展示友好的提示信息，甚至在特定条件下尝试恢复导航（这需要你手动调用next()或router.push()）。

来看一个具体的示例：

const router = createRouter({ ... })

router.onError((error) => {
  console.error('路由跳转异常:', error)
  if (error?.code === 'AUTH_REQUIRED') {
    router.push('/login')
  } else if (error?.name === 'Na vigationFailure') {
    // 忽略已知的导航失败（如重复跳转）
  } else {
    router.push('/500')
  }
})

app.use(router)

配合守卫主动抛错，提升可维护性

与其在各个守卫函数里塞满if-else判断和router.push跳转逻辑，不如采用一种更清晰、更解耦的策略：让守卫专注于“判断”和“抛出”，而将统一的“响应”工作交给onError处理器。

• 在beforeEach中检查用户登录状态，如果未登录，直接throw { code: 'NOT_LOGGED_IN' }。
• 当权限校验失败时，抛出throw new Error('Permission denied')，然后在onError中根据错误信息映射到对应的无权限页面或提示框。
• 这样做的好处显而易见：避免了错误处理逻辑在多个守卫中重复出现，保持了守卫代码的纯粹性，也让错误处理的流程变得集中且易于管理。

注意异步守卫的错误捕获边界

需要特别留意的是，onError并非万能。它只负责捕获守卫函数执行期间同步或异步抛出的错误。对于组件setup或onBeforeRouteUpdate生命周期钩子中未被妥善处理的Promise拒绝，它是无能为力的。因此，务必确保以下几点：

• 在异步守卫中，所有Promise都必须被await或通过.catch()方法处理，否则可能导致Promise静默拒绝，错误无法被捕获。
• 不要在守卫逻辑中遗漏return next(false)或显式的router.push()调用，否则导航流程可能会被意外设起，陷入等待状态。
• 在调试阶段，一个快速定位问题的小技巧是：在onError处理器中临时使用alert(error.message)，可以立刻看到错误的源头信息。