以下将深入讲解 Vue Router 的全局前置守卫 beforeEach 在权限系统中的实现原理和实战应用，结合企业级项目代码进行拆解（基于 Vue 3 + TypeScript + Pinia）。
一、前置守卫核心机制
1.1 执行时机与特性
全局前置守卫在路由跳转前触发，具有以下特性：
- 拦截所有导航：包括手动 URL 输入、
router-link跳转、编程式导航（router.push） - 异步解析：支持 Promise 链式调用，适用于需要等待接口响应的场景
- 拦截优先级：触发顺序为
组件内 beforeRouteLeave→全局 beforeEach→路由独享 beforeEnter
1.2 参数解析
router.beforeEach((to, from, next) => {// to: 目标路由对象（含 path/params/meta 等）// from: 来源路由对象// next: 导航控制函数
})
参数特性：
to.matched：获取嵌套路由的所有匹配记录（用于检查深层路由权限）meta字段扩展性：可在路由配置中自定义权限标识
二、权限校验实现步骤
2.1 路由元信息配置
在路由配置中声明权限标识：
// router.ts
const routes = [{path: '/dashboard',component: Dashboard,meta: {requiresAuth: true, // 需要登录permissions: ['admin'], // 所需权限dynamicMenu: true // 动态菜单标识}},{path: '/login',component: Login,meta: {guestOnly: true // 仅允许未登录用户访问}}
]
2.2 权限校验主逻辑
// permission.ts
export const permissionGuard: NavigationGuard = async (to, from, next) => {const authStore = useAuthStore() // Pinia 状态管理// 1. 检查登录状态if (to.meta.requiresAuth && !authStore.isAuthenticated) {return next({ path: '/login',query: { redirect: to.fullPath } // 记录原始目标路径})}// 2. 已登录用户访问登录页重定向if (to.meta.guestOnly && authStore.isAuthenticated) {return next(from.path || '/')}// 3. 动态权限加载（首次加载或Token刷新后）if (!authStore.permissionsLoaded) {try {await authStore.fetchPermissions()} catch (error) {next('/500') // 接口异常处理return}}// 4. 细粒度权限校验if (to.meta.permissions) {const hasPermission = authStore.userPermissions.some(perm => to.meta.permissions!.includes(perm))if (!hasPermission) {next('/403') // 无权限页面return}}// 5. 动态路由注入（异步加载权限路由）if (to.meta.dynamicMenu && !isRouteExists(to)) {const dynamicRoutes = await fetchDynamicRoutes()dynamicRoutes.forEach(route => router.addRoute(route))next(to.fullPath) // 重新触发导航return}next() // 放行
}
三、登录状态检查进阶方案
3.1 状态持久化方案
// stores/auth.ts (Pinia)
export const useAuthStore = defineStore('auth', {state: () => ({token: localStorage.getItem('token') || null,user: null as User | null,permissions: [] as string[]}),actions: {async login(credentials: LoginForm) {const { data } = await api.login(credentials)this.token = data.tokenthis.user = data.userlocalStorage.setItem('token', data.token)router.push(data.redirect || '/')},logout() {this.token = nullthis.user = nulllocalStorage.removeItem('token')router.replace('/login')}},getters: {isAuthenticated: state => !!state.token}
})
3.2 Token 自动续期
// axios 拦截器
instance.interceptors.response.use(response => response,async error => {const originalRequest = error.configif (error.response.status === 401 && !originalRequest._retry) {originalRequest._retry = truetry {const newToken = await refreshToken()authStore.token = newTokenoriginalRequest.headers.Authorization = `Bearer ${newToken}`return instance(originalRequest)} catch (refreshError) {authStore.logout()return Promise.reject(refreshError)}}return Promise.reject(error)}
)
四、企业级项目整合方案
4.1 路由守卫注册
// main.ts
import router from './router'
import { permissionGuard } from './permission'router.beforeEach(async (to, from, next) => {// 页面加载进度条NProgress.start()// 执行权限校验链await permissionGuard(to, from, next)NProgress.done()
})router.afterEach(() => {// 页面访问统计trackPageView(to.fullPath)
})
4.2 动态路由加载
// 获取动态路由
const fetchDynamicRoutes = async () => {const { data } = await api.get('/routes')return data.map(route => ({path: route.path,component: () => import(`@/views/${route.component}.vue`),meta: route.meta}))
}// 处理动态路由的404情况
router.onError((error) => {if (/Loading chunk .+ failed/.test(error.message)) {window.location.reload()}
})
五、最佳实践与调试技巧
5.1 调试建议
// 开发环境打印导航日志
if (import.meta.env.DEV) {router.beforeEach((to, from) => {console.log('[Route]', from.path, '→', to.path)console.log('[Meta]', to.meta)})
}
5.2 常见问题处理
-
无限重定向问题
检查重定向条件是否互斥：if (to.path === '/login' && authStore.isAuthenticated) {next(from.path || '/') // 避免循环 } -
路由切换白屏
使用路由懒加载 + Suspense：<template><Suspense><RouterView /></Suspense> </template> -
权限变更同步
监听权限变化事件：watch(() => authStore.permissions, () => {router.replace(currentRoute.value.fullPath) })
六、扩展功能实现
6.1 多租户权限系统
// 路由配置增加租户标识
meta: {tenant: 'A',permissions: ['report:view']
}// 守卫中校验租户
if (to.meta.tenant !== authStore.currentTenant) {next('/tenant-switch')
}
6.2 页面水印防护
router.afterEach((to) => {if (to.meta.sensitive) {applyWatermark(authStore.username)}
})
总结
全局前置守卫作为权限系统的核心入口，需要结合以下关键点实现：
- 状态管理：通过 Pinia/Vuex 实现跨组件状态共享
- 路由分层：静态路由 + 动态加载实现灵活权限分配
- 错误边界：完善的异常处理流程（401/403/404）
- 性能优化：路由懒加载、接口缓存、防抖处理
