Vue 路由守卫实战：导航守卫与权限控制的完整方案

快速概述

Vue 路由守卫是 Vue Router 提供的导航拦截机制，用于在路由跳转前后执行逻辑，核心解决页面访问权限控制、登录状态校验、数据预取等场景问题。前置环境要求：Vue 3 项目已安装 Vue Router 4，或 Vue 2 项目使用 Vue Router 3。Vue 作为渐进式框架，可基于标准 HTML、CSS 和 JavaScript 构建，提供容易上手的 API 和一流的文档。

核心概念与原理

路由守卫本质是导航过程中的钩子函数，Vue Router 在导航被触发时按顺序执行一系列守卫，开发者可在其中返回 true 放行、返回 false 取消导航，或返回新路径进行重定向。守卫分为三类：全局守卫（beforeEach、beforeResolve、afterEach）、路由独享守卫（beforeEnter）和组件内守卫（beforeRouteEnter、beforeRouteUpdate、beforeRouteLeave）。权限控制的核心模式是在全局前置守卫中读取目标路由的 meta 元信息，与当前用户角色比对后决定放行或跳转登录页。

实战步骤与代码

第一步：定义路由并配置 meta 权限标记

// router/index.js
import { createRouter, createWebHistory } from 'vue-router'
const routes = [ { path: '/admin', component: () => import('@/views/Admin.vue'), meta: { requiresAuth: true, roles: ['admin'] } // 需要登录且仅 admin 可访问 }, { path: '/profile', component: () => import('@/views/Profile.vue'), meta: { requiresAuth: true } // 仅需登录 }, { path: '/login', component: () => import('@/views/Login.vue') } ]
export default createRouter({ history: createWebHistory(), routes })

第二步：编写全局前置守卫

// router/index.js 追加
router.beforeEach((to, from, next) => {
  const token = localStorage.getItem('token') // 获取登录凭证
  const userRole = localStorage.getItem('role') // 获取用户角色
if (to.meta.requiresAuth && !token) { next({ path: '/login', query: { redirect: to.fullPath } }) // 未登录跳转登录页 } else if (to.meta.roles && !to.meta.roles.includes(userRole)) { next('/403') // 角色不匹配跳转 403 页面 } else { next() // 放行 } })

第三步：路由独享守卫与组件内守卫

// 路由独享守卫：在路由配置中直接添加
const routes = [
  {
    path: '/editor',
    component: Editor,
    beforeEnter: (to, from, next) => {
      // 仅编辑角色可进入
      if (localStorage.getItem('role') === 'editor') next()
      else next('/403')
    }
  }
]
// 组件内守卫：在组件中定义 export default { beforeRouteEnter(to, from, next) { // 进入前调用，此时组件实例尚未创建，无法访问 this next(vm => { /* 通过 vm 访问组件实例 */ }) }, beforeRouteLeave(to, from, next) { // 离开前调用，可做未保存提示 const answer = window.confirm('确认离开？') answer ? next() : next(false) } }

常见坑点与优化

• next 函数重复调用：在守卫中调用 next 后再次调用会触发警告，务必确保每个分支只调用一次。
• 异步权限获取：从后端获取用户角色是异步操作，需在守卫中使用 async/await 或 Promise 后再调用 next，避免未拿到角色就放行。
• 死循环问题：重定向到 /login 时若登录页也配置了 requiresAuth，会导致无限循环，需对登录页单独放行。
• 组件内 beforeRouteEnter 无法访问 this：此时组件尚未创建，需通过 next 回调参数 vm 访问实例。
• 性能优化：将路由组件改为动态导入（代码分割），减少首屏加载体积；避免在守卫中执行重计算逻辑，可将角色信息缓存于 Pinia 或本地存储。

Vue 2.0 在 2023 年 12 月 31 日停止更新，新项目建议直接使用 Vue 3 与 Vue Router 4。Vue 只关注视图层，采用自底向上增量开发的设计，路由守卫作为生态核心模块，与 Pinia 状态管理配合可构建完整的权限体系。