在Vue单页应用SPA开发中路由跳转是核心交互逻辑而**路由守卫**则是掌控路由跳转流程、实现页面权限控制、登录校验、页面跳转拦截等功能的关键工具。不管是Vue2搭配Vue Router 3还是Vue3搭配Vue Router 4路由守卫的核心逻辑高度一致只是语法细节略有差异。这篇博客会从零开始全面拆解Vue路由守卫的分类、用法、实战场景和常见坑帮你彻底吃透路由守卫轻松实现登录拦截、页面权限、路由跳转监听等刚需功能。一、什么是路由守卫路由守卫简单来说就是**路由跳转的“拦截器”和“监听器”**可以在路由跳转的不同生命周期节点执行自定义逻辑决定路由是否跳转、修改跳转目标或者执行额外操作。核心作用登录状态校验未登录用户禁止访问私密页面自动跳转登录页页面权限控制不同角色用户管理员/普通用户访问对应页面路由跳转监听监听页面进入、离开做数据清理、埋点上报表单防误退编辑页面未保存拦截返回跳转并提示用户动态路由匹配结合权限动态生成可访问路由Vue路由守卫按照作用范围和触发时机主要分为三大类全局守卫、路由独享守卫、组件内守卫接下来逐一详解。二、路由守卫分类与详细用法2.1 全局守卫作用于所有路由全局守卫一旦注册会对项目中所有路由跳转生效通常用于全局登录校验、全局权限判断在路由入口文件router/index.js中注册。2.1.1 全局前置守卫 beforeEach触发时机路由跳转开始进入路由之前触发是最常用的守卫适合做登录拦截、权限校验。核心参数to即将要进入的目标路由对象from当前正要离开的路由对象next放行函数控制路由是否跳转Vue Router 4可省略next直接返回布尔值/路径Vue3 Vue Router 4 写法推荐// router/index.js import { createRouter, createWebHistory } from vue-router import Login from /views/Login.vue import Home from /views/Home.vue const routes [ { path: /login, name: Login, component: Login }, { path: /home, name: Home, component: Home, meta: { requiresAuth: true } } ] const router createRouter({ history: createWebHistory(), routes }) // 全局前置守卫 router.beforeEach((to, from) { // 判断目标路由是否需要登录权限 if (to.meta.requiresAuth) { // 模拟获取本地token const token localStorage.getItem(token) if (!token) { // 未登录跳转登录页 return { name: Login } } } // 已登录或无需权限直接放行 return true }) export default routerVue2 Vue Router 3 写法router.beforeEach((to, from, next) { if (to.meta.requiresAuth) { const token localStorage.getItem(token) token ? next() : next(/login) } else { next() } })重点提示Vue Router 4 中next是非必传参数直接return true代表放行return 路径/路由对象代表重定向return false代表拦截跳转Vue Router 3必须调用next否则路由会卡死。2.1.2 全局解析守卫 beforeResolve触发时机在beforeEach之后组件内守卫和异步路由组件解析完成之后触发所有守卫执行完路由正式跳转前。适用场景需要等待异步路由加载完成、组件内守卫执行完毕后再做最终校验比如数据预加载、最终权限确认。router.beforeResolve((to, from) { console.log(全局解析守卫触发) return true })2.1.3 全局后置守卫 afterEach触发时机路由跳转完成之后触发没有next参数无法拦截路由。适用场景页面标题修改、埋点上报、页面加载进度条关闭、滚动行为重置。router.afterEach((to) { // 修改页面标题 document.title to.meta.title || Vue项目 // 关闭加载进度条 NProgress.done() })2.2 路由独享守卫作用于单个路由beforeEnter写在路由配置项里只对当前单个路由生效优先级低于全局守卫适合单个页面的独立校验避免全局守卫代码臃肿。触发时机进入当前路由时触发和beforeEach逻辑一致仅作用于当前路由。const routes [ { path: /admin, name: Admin, component: () import(/views/Admin.vue), meta: { requiresAuth: true }, // 路由独享守卫 beforeEnter: (to, from) { // 仅管理员可访问 const role localStorage.getItem(userRole) if (role ! admin) { return { name: Home } } return true } } ]2.3 组件内守卫作用于单个组件写在Vue组件内部针对当前组件的路由跳转做监听分为进入、更新、离开三个阶段适合组件级别的逻辑处理比如表单防误退、组件内数据监听。2.3.1 beforeRouteEnter触发时机进入组件前触发此时组件实例还未创建无法访问this。解决方案通过next回调获取组件实例。// Vue3 组合式API写法 import { onBeforeRouteEnter } from vue-router onBeforeRouteEnter((to, from, next) { console.log(组件进入前) next(vm { // vm代表组件实例可通过vm访问组件数据和方法 vm.initPageData() }) })2.3.2 beforeRouteUpdate触发时机路由参数更新时触发比如动态路由 /detail/:idid变化组件复用时触发可访问this。适用场景列表页跳转到详情页复用组件时刷新数据。import { onBeforeRouteUpdate } from vue-router onBeforeRouteUpdate((to) { // 路由参数变化重新获取数据 const id to.params.id this.getDetailData(id) })2.3.3 beforeRouteLeave触发时机离开当前组件时触发可访问this最常用的场景是表单防误退。import { onBeforeRouteLeave } from vue-router onBeforeRouteLeave((to, from) { // 表单未保存拦截跳转并提示 if (this.formIsChange) { return window.confirm(页面内容未保存确定离开吗) } return true })注意Vue3组合式API中组件内守卫需要从vue-router导入对应的钩子函数Vue2选项式API则直接写在配置项里beforeRouteEnter、beforeRouteUpdate、beforeRouteLeave。三、路由守卫执行顺序核心重点理清路由守卫执行顺序才能避免逻辑冲突完整顺序如下触发路由跳转全局前置守卫 beforeEach路由独享守卫 beforeEnter组件内守卫 beforeRouteEnter全局解析守卫 beforeResolve全局后置守卫 afterEach组件生命周期触发mounted等如果是路由参数更新组件复用只会触发beforeRouteUpdate不会触发其他守卫。四、高频实战场景4.1 登录状态全局拦截最常用通过路由meta元信息标记需要登录的页面全局前置守卫统一校验token未登录自动跳转登录页登录后跳回原页面。router.beforeEach((to, from) { const token localStorage.getItem(token) // 白名单页面无需登录 const whiteList [Login, Register, Home] if (whiteList.includes(to.name)) return true if (!token) { // 记录目标路由登录后跳转回去 return { name: Login, query: { redirect: to.fullPath } } } return true }) // 登录页登录成功后 const loginSuccess () { localStorage.setItem(token, xxxx) // 跳回原页面无原页面则跳首页 const redirect route.query.redirect || /home router.push(redirect) }4.2 表单页面防误退编辑页面用户输入内容未保存离开时弹出提示避免数据丢失。import { ref } from vue import { onBeforeRouteLeave } from vue-router // 表单数据 const formData ref({}) // 标记表单是否修改 const formIsChange ref(false) onBeforeRouteLeave(() { if (formIsChange.value) { return confirm(当前编辑内容未保存确认离开将会丢失数据是否继续) } })4.3 角色权限控制结合用户角色拦截无权限页面访问适配后台管理系统权限场景。router.beforeEach((to) { const token localStorage.getItem(token) const userRole localStorage.getItem(role) // 需要权限的页面 if (to.meta.roles !to.meta.roles.includes(userRole)) { return { name: 403 } } return true }) // 路由配置 { path: /order, component: Order, meta: { roles: [admin, editor] } }五、常见坑与避坑指南Vue Router 3 忘记调用next路由会卡死必须确保所有分支都调用next全局守卫死循环登录页校验时未排除白名单反复跳转登录页务必加白名单判断beforeRouteEnter无法访问this通过next回调获取实例不要直接使用this动态路由参数更新不触发守卫用beforeRouteUpdate监听参数变化刷新组件数据afterEach无法拦截路由不要在afterEach里做校验拦截仅用于后置操作六、总结Vue路由守卫是SPA路由管理的核心按照作用范围分为全局、路由独享、组件内三类核心用法围绕登录拦截、权限控制、路由监听、防误退四大场景。日常开发中全局前置守卫beforeEach使用频率最高负责全局校验组件内beforeRouteLeave适合表单防误退beforeEnter适合单一路由权限控制。掌握执行顺序和避坑技巧就能轻松搞定各类路由拦截需求。后续还可以结合动态路由、路由懒加载实现更精细化的权限管理体系适配复杂后台系统开发。
Vue路由守卫全解析：从入门到实战，一文搞定权限控制与路由拦截
在Vue单页应用SPA开发中路由跳转是核心交互逻辑而**路由守卫**则是掌控路由跳转流程、实现页面权限控制、登录校验、页面跳转拦截等功能的关键工具。不管是Vue2搭配Vue Router 3还是Vue3搭配Vue Router 4路由守卫的核心逻辑高度一致只是语法细节略有差异。这篇博客会从零开始全面拆解Vue路由守卫的分类、用法、实战场景和常见坑帮你彻底吃透路由守卫轻松实现登录拦截、页面权限、路由跳转监听等刚需功能。一、什么是路由守卫路由守卫简单来说就是**路由跳转的“拦截器”和“监听器”**可以在路由跳转的不同生命周期节点执行自定义逻辑决定路由是否跳转、修改跳转目标或者执行额外操作。核心作用登录状态校验未登录用户禁止访问私密页面自动跳转登录页页面权限控制不同角色用户管理员/普通用户访问对应页面路由跳转监听监听页面进入、离开做数据清理、埋点上报表单防误退编辑页面未保存拦截返回跳转并提示用户动态路由匹配结合权限动态生成可访问路由Vue路由守卫按照作用范围和触发时机主要分为三大类全局守卫、路由独享守卫、组件内守卫接下来逐一详解。二、路由守卫分类与详细用法2.1 全局守卫作用于所有路由全局守卫一旦注册会对项目中所有路由跳转生效通常用于全局登录校验、全局权限判断在路由入口文件router/index.js中注册。2.1.1 全局前置守卫 beforeEach触发时机路由跳转开始进入路由之前触发是最常用的守卫适合做登录拦截、权限校验。核心参数to即将要进入的目标路由对象from当前正要离开的路由对象next放行函数控制路由是否跳转Vue Router 4可省略next直接返回布尔值/路径Vue3 Vue Router 4 写法推荐// router/index.js import { createRouter, createWebHistory } from vue-router import Login from /views/Login.vue import Home from /views/Home.vue const routes [ { path: /login, name: Login, component: Login }, { path: /home, name: Home, component: Home, meta: { requiresAuth: true } } ] const router createRouter({ history: createWebHistory(), routes }) // 全局前置守卫 router.beforeEach((to, from) { // 判断目标路由是否需要登录权限 if (to.meta.requiresAuth) { // 模拟获取本地token const token localStorage.getItem(token) if (!token) { // 未登录跳转登录页 return { name: Login } } } // 已登录或无需权限直接放行 return true }) export default routerVue2 Vue Router 3 写法router.beforeEach((to, from, next) { if (to.meta.requiresAuth) { const token localStorage.getItem(token) token ? next() : next(/login) } else { next() } })重点提示Vue Router 4 中next是非必传参数直接return true代表放行return 路径/路由对象代表重定向return false代表拦截跳转Vue Router 3必须调用next否则路由会卡死。2.1.2 全局解析守卫 beforeResolve触发时机在beforeEach之后组件内守卫和异步路由组件解析完成之后触发所有守卫执行完路由正式跳转前。适用场景需要等待异步路由加载完成、组件内守卫执行完毕后再做最终校验比如数据预加载、最终权限确认。router.beforeResolve((to, from) { console.log(全局解析守卫触发) return true })2.1.3 全局后置守卫 afterEach触发时机路由跳转完成之后触发没有next参数无法拦截路由。适用场景页面标题修改、埋点上报、页面加载进度条关闭、滚动行为重置。router.afterEach((to) { // 修改页面标题 document.title to.meta.title || Vue项目 // 关闭加载进度条 NProgress.done() })2.2 路由独享守卫作用于单个路由beforeEnter写在路由配置项里只对当前单个路由生效优先级低于全局守卫适合单个页面的独立校验避免全局守卫代码臃肿。触发时机进入当前路由时触发和beforeEach逻辑一致仅作用于当前路由。const routes [ { path: /admin, name: Admin, component: () import(/views/Admin.vue), meta: { requiresAuth: true }, // 路由独享守卫 beforeEnter: (to, from) { // 仅管理员可访问 const role localStorage.getItem(userRole) if (role ! admin) { return { name: Home } } return true } } ]2.3 组件内守卫作用于单个组件写在Vue组件内部针对当前组件的路由跳转做监听分为进入、更新、离开三个阶段适合组件级别的逻辑处理比如表单防误退、组件内数据监听。2.3.1 beforeRouteEnter触发时机进入组件前触发此时组件实例还未创建无法访问this。解决方案通过next回调获取组件实例。// Vue3 组合式API写法 import { onBeforeRouteEnter } from vue-router onBeforeRouteEnter((to, from, next) { console.log(组件进入前) next(vm { // vm代表组件实例可通过vm访问组件数据和方法 vm.initPageData() }) })2.3.2 beforeRouteUpdate触发时机路由参数更新时触发比如动态路由 /detail/:idid变化组件复用时触发可访问this。适用场景列表页跳转到详情页复用组件时刷新数据。import { onBeforeRouteUpdate } from vue-router onBeforeRouteUpdate((to) { // 路由参数变化重新获取数据 const id to.params.id this.getDetailData(id) })2.3.3 beforeRouteLeave触发时机离开当前组件时触发可访问this最常用的场景是表单防误退。import { onBeforeRouteLeave } from vue-router onBeforeRouteLeave((to, from) { // 表单未保存拦截跳转并提示 if (this.formIsChange) { return window.confirm(页面内容未保存确定离开吗) } return true })注意Vue3组合式API中组件内守卫需要从vue-router导入对应的钩子函数Vue2选项式API则直接写在配置项里beforeRouteEnter、beforeRouteUpdate、beforeRouteLeave。三、路由守卫执行顺序核心重点理清路由守卫执行顺序才能避免逻辑冲突完整顺序如下触发路由跳转全局前置守卫 beforeEach路由独享守卫 beforeEnter组件内守卫 beforeRouteEnter全局解析守卫 beforeResolve全局后置守卫 afterEach组件生命周期触发mounted等如果是路由参数更新组件复用只会触发beforeRouteUpdate不会触发其他守卫。四、高频实战场景4.1 登录状态全局拦截最常用通过路由meta元信息标记需要登录的页面全局前置守卫统一校验token未登录自动跳转登录页登录后跳回原页面。router.beforeEach((to, from) { const token localStorage.getItem(token) // 白名单页面无需登录 const whiteList [Login, Register, Home] if (whiteList.includes(to.name)) return true if (!token) { // 记录目标路由登录后跳转回去 return { name: Login, query: { redirect: to.fullPath } } } return true }) // 登录页登录成功后 const loginSuccess () { localStorage.setItem(token, xxxx) // 跳回原页面无原页面则跳首页 const redirect route.query.redirect || /home router.push(redirect) }4.2 表单页面防误退编辑页面用户输入内容未保存离开时弹出提示避免数据丢失。import { ref } from vue import { onBeforeRouteLeave } from vue-router // 表单数据 const formData ref({}) // 标记表单是否修改 const formIsChange ref(false) onBeforeRouteLeave(() { if (formIsChange.value) { return confirm(当前编辑内容未保存确认离开将会丢失数据是否继续) } })4.3 角色权限控制结合用户角色拦截无权限页面访问适配后台管理系统权限场景。router.beforeEach((to) { const token localStorage.getItem(token) const userRole localStorage.getItem(role) // 需要权限的页面 if (to.meta.roles !to.meta.roles.includes(userRole)) { return { name: 403 } } return true }) // 路由配置 { path: /order, component: Order, meta: { roles: [admin, editor] } }五、常见坑与避坑指南Vue Router 3 忘记调用next路由会卡死必须确保所有分支都调用next全局守卫死循环登录页校验时未排除白名单反复跳转登录页务必加白名单判断beforeRouteEnter无法访问this通过next回调获取实例不要直接使用this动态路由参数更新不触发守卫用beforeRouteUpdate监听参数变化刷新组件数据afterEach无法拦截路由不要在afterEach里做校验拦截仅用于后置操作六、总结Vue路由守卫是SPA路由管理的核心按照作用范围分为全局、路由独享、组件内三类核心用法围绕登录拦截、权限控制、路由监听、防误退四大场景。日常开发中全局前置守卫beforeEach使用频率最高负责全局校验组件内beforeRouteLeave适合表单防误退beforeEnter适合单一路由权限控制。掌握执行顺序和避坑技巧就能轻松搞定各类路由拦截需求。后续还可以结合动态路由、路由懒加载实现更精细化的权限管理体系适配复杂后台系统开发。
