Vue/React路由守卫权威指南：三步构建无懈可击的前端权限管理系统
路由守卫是前端权限体系的核心组件，它远不止于简单的页面访问控制。一个设计不当的守卫逻辑，会导致用户越权访问、页面跳转卡顿、数据加载异常等一系列问题。你是否遇到过未登录用户直接进入个人中心，或普通用户意外打开管理员后台的情况？这些正是路由守卫需要精准拦截的场景。
本文将为你拆解路由守卫的核心实现逻辑，并提供一套可直接复用的封装方案。无论你的技术栈是Vue 2、Vue 3还是React，其权限验证的核心范式是相通的——即通过登录状态校验、用户角色匹配和导航生命周期钩子来构建安全防线。以下代码方案能帮你规避权限控制中最常见的四个陷阱。
一、先搞懂：路由守卫到底用来做什么？
无论是Vue Router的导航守卫，还是React Router的组件封装模式，其核心职责都是作为应用导航的“守门员”。它确保每次路由跳转都符合业务规则，主要解决以下四个关键问题：
- 权限拦截：验证用户身份凭证，阻止未授权访问受保护的路由，如个人中心或订单管理页面。
- 角色隔离：基于用户角色（如user、admin）动态控制可访问的路由集合，实现前端层面的权限隔离。
- 操作确认：在用户离开包含未保存状态的页面（如表单编辑页）前触发二次确认，防止数据丢失。
- 数据预加载：在路由组件渲染前预先获取依赖数据，避免页面出现空白或加载状态，提升用户体验。
本质上，路由守卫是连接用户身份与界面资源的桥梁。Vue和React在API设计上虽有差异，但实现权限流的底层逻辑一致。接下来，我们将分别解析两大框架下的最佳实践。
二、核心干货：Vue2/Vue3 路由守卫完整封装
在Vue Router体系中，守卫分为全局、路由独享和组件内三个层级。对于大多数应用，全局前置守卫（`beforeEach`）足以处理80%的权限校验需求。
1. Vue3 + Vue Router 4（最常用，推荐）
在`router/index.js`中，集中配置路由元信息并实现全局守卫逻辑：
// router/index.js（Vue3）
import { createRouter, createWebHistory } from 'vue-router';
import { getStorage } from '@/utils/storage'; // 假设你有一个封装好的本地存储工具
// 1. 定义路由（这里关键是把公开路由和需要权限的路由区分开）
const routes = [
// 公开路由，谁都能访问
{
path: '/login',
name: 'Login',
component: () => import('@/views/Login.vue'),
meta: { requiresAuth: false } // 标记：不需要权限
},
{
path: '/',
name: 'Home',
component: () => import('@/views/Home.vue'),
meta: { requiresAuth: false }
},
// 需要登录才能访问的路由
{
path: '/user',
name: 'UserCenter',
component: () => import('@/views/UserCenter.vue'),
meta: {
requiresAuth: true, // 标记：需要权限
role: 'user' // 进一步限制：普通用户角色即可
}
},
// 管理员专属路由
{
path: '/admin',
name: 'Admin',
component: () => import('@/views/Admin.vue'),
meta: {
requiresAuth: true,
role: 'admin' // 限制：仅管理员角色
}
},
// 404页面兜底
{
path: '/:pathMatch(.*)*',
name: '404',
component: () => import('@/views/404.vue')
}
];
// 2. 创建路由实例
const router = createRouter({
history: createWebHistory(import.meta.env.VITE_BASE_URL),
routes
});
// 3. 全局前置守卫（核心中的核心，每次跳转前都会执行）
router.beforeEach((to, from, next) => {
// 1. 从本地存储获取登录凭证
const token = getStorage('token');
// 2. 获取当前用户的角色信息
const userRole = getStorage('userInfo')?.role || '';
// 3. 权限校验逻辑
if (to.meta.requiresAuth) {
// 3.1 目标页面需要权限
if (!token) {
// 没登录？跳转到登录页，并记下用户本来想去哪儿
return next({ name: 'Login', query: { redirect: to.fullPath } });
} else {
// 已登录，检查角色是否匹配页面要求
if (to.meta.role && to.meta.role !== userRole) {
// 角色不对？跳回首页或指定的403页面
return next({ name: 'Home' });
}
// 登录和角色都通过，放行
next();
}
} else {
// 3.2 公开页面，直接放行
next();
}
});
// 4. 全局后置守卫（跳转完成后执行，适合改改页面标题啥的）
router.afterEach((to) => {
document.title = to.meta.title || '前端路由守卫示例';
});
export default router;登录成功后，需处理重定向逻辑，引导用户返回原始目标页面：
<script setup>
import { useRouter, useRoute } from 'vue-router';
import { setStorage } from '@/utils/storage';
const router = useRouter();
const route = useRoute();
const login = async () => {
const res = await loginApi(); // 调用你的登录接口
// 存储token和用户信息
setStorage('token', res.data.token, 86400);
setStorage('userInfo', res.data.user, 86400);
// 跳转回之前的页面（如果有的话），否则去首页
const redirect = route.query.redirect || '/';
router.push(redirect);
};
</script>2. Vue2 + Vue Router 3（兼容旧项目）
核心逻辑与Vue3版本一致，仅语法和API存在细微差异：
// router/index.js（Vue2）
import Vue from 'vue';
import Router from 'vue-router';
import { getStorage } from '@/utils/storage';
Vue.use(Router);
const routes = [
// 路由配置和Vue3版本一致
{ path: '/login', name: 'Login', component: () => import('@/views/Login'), meta: { requiresAuth: false } },
{ path: '/user', name: 'UserCenter', component: () => import('@/views/UserCenter'), meta: { requiresAuth: true, role: 'user' } },
{ path: '/admin', name: 'Admin', component: () => import('@/views/Admin'), meta: { requiresAuth: true, role: 'admin' } },
];
const router = new Router({
mode: 'history',
base: process.env.BASE_URL,
routes
});
// 全局前置守卫
router.beforeEach((to, from, next) => {
const token = getStorage('token');
const userRole = getStorage('userInfo')?.role || '';
if (to.meta.requiresAuth) {
if (!token) {
next({ name: 'Login', query: { redirect: to.fullPath } });
} else {
if (to.meta.role && to.meta.role !== userRole) {
next({ name: 'Home' });
} else {
next();
}
}
} else {
next();
}
});
export default router;三、核心干货：React + React Router 6 路由守卫封装（直接复制）
React Router 6采用了声明式的路由守卫模式，取消了传统的`beforeEach`API，转而通过封装高阶组件或自定义路由元素来实现权限控制。这种方式更贴合React的函数式编程范式。
1. 封装权限守卫组件（utils/PrivateRoute.js）
创建一个可复用的权限验证组件：
import { Na vigate, Outlet } from 'react-router-dom';
import { getStorage } from '@/utils/storage';
/**
* 权限守卫组件
* @param {Object} props - 传入的属性
* @param {string} props.role - 允许访问的角色（可选）
*/
export const PrivateRoute = ({ role }) => {
// 获取登录态和用户角色
const token = getStorage('token');
const userRole = getStorage('userInfo')?.role || '';
// 情况1: 未登录，重定向到登录页
if (!token) {
return 2. 路由配置（router/index.jsx）
在路由定义中，将需要保护的路由用`PrivateRoute`组件包裹：
import { createBrowserRouter } from 'react-router-dom';
import PrivateRoute from '@/utils/PrivateRoute';
// 引入页面组件
import Login from '@/views/Login';
import Home from '@/views/Home';
import UserCenter from '@/views/UserCenter';
import Admin from '@/views/Admin';
import NotFound from '@/views/404';
// 创建路由
const router = createBrowserRouter([
{
path: '/',
element: 3. 入口文件中使用（main.jsx）
import React from 'react';
import ReactDOM from 'react-dom/client';
import { RouterProvider } from 'react-router-dom';
import router from './router';
ReactDOM.createRoot(document.getElementById('root')).render(
);4. React 登录页面使用
登录成功后，需从URL查询参数中提取重定向地址并跳转：
import { useNa vigate, useLocation } from 'react-router-dom';
import { setStorage } from '@/utils/storage';
function Login() {
const na vigate = useNa vigate();
const location = useLocation();
// 从查询参数中获取跳转前的地址
const redirect = new URLSearchParams(location.search).get('redirect') || '/';
const login = async () => {
const res = await loginApi();
setStorage('token', res.data.token, 86400);
setStorage('userInfo', res.data.user, 86400);
// 跳转回之前的页面
na vigate(redirect, { replace: true });
};
return (
);
}
export default Login;四、实战避坑：4 个高频坑，新手必避
实现基础守卫逻辑后，以下四个细节问题若处理不当，仍会导致功能异常或安全漏洞。
坑 1：Vue 路由守卫中，忘记调用 next()，导致页面卡死
这是最常见的错误。在`beforeEach`中，每个逻辑分支都必须显式调用`next()`函数，否则路由跳转会永久挂起。确保在权限校验的每个条件判断后，都执行`next()`或`next(path)`。
坑 2：React Router 6 中，还在用旧版本语法写守卫
React Router 6移除了`onEnter`、`beforeEach`等旧API。若沿用v5的类组件模式或错误引用过时教程，守卫将无法生效。正确的做法是封装一个权限验证组件，并将其作为路由的`element`属性值。
坑 3：未处理“登录后跳转回原页面”，体验变差
拦截未登录用户后，若登录成功后仅跳转至首页，会打断用户操作流。最佳实践是在重定向至登录页时，通过`redirect`查询参数携带原始目标路径，登录成功后据此进行精确导航。
坑 4：角色权限判断不严谨，导致越权访问
仅验证登录状态而忽略角色校验，是权限系统的重大缺陷。攻击者可能通过直接输入URL访问未授权资源。必须在路由元信息（Vue的`meta`）或组件属性（React的`props`）中明确定义所需角色，并在守卫逻辑中进行严格比对。
五、进阶技巧：路由守卫高级用法
掌握基础权限控制后，路由守卫还可用于实现更精细的交互与状态管理。
1. 表单未保存，禁止跳转（组件内守卫 / Vue 专属）
利用Vue Router的组件内守卫`onBeforeRouteLeave`，在用户离开未保存的表单页前进行提示：
<script setup>
import { onBeforeRouteLea ve } from 'vue-router';
// 组件内守卫：离开当前页面时触发
onBeforeRouteLea ve((to, from, next) => {
// 判断表单是否有未保存的改动
if (formIsDirty.value) {
if (confirm('表单未保存，确定要离开吗？')) {
next(); // 用户确认离开
} else {
next(false); // 用户取消，留在当前页
}
} else {
next(); // 表单干净，直接放行
}
});
</script>2. 路由跳转时，加载 loading 状态（全局守卫）
通过全局守卫与响应式状态结合，统一管理页面切换时的加载动画：
// 在Vue3全局守卫中集成loading状态
import { ref } from 'vue';
export const isLoading = ref(false);
router.beforeEach((to, from, next) => {
isLoading.value = true; // 跳转开始，显示loading
// ... 这里是你原有的权限校验逻辑
next();
});
router.afterEach(() => {
// 跳转完成，稍作延迟后隐藏loading（让页面渲染更平滑）
setTimeout(() => {
isLoading.value = false;
}, 300);
});六、结尾：干货总结
路由守卫是实现前端权限控制的标准化方案。其核心职责可归纳为三点：身份验证（Authentication）、权限校验（Authorization）和导航控制（Navigation Control）。
本文提供的封装代码已覆盖主流框架下的常见业务场景。你可直接将其集成到项目中，并根据实际业务调整路由元数据与角色逻辑，即可快速构建稳健的前端权限防线。注意规避上述四个高频陷阱，你的路由守卫将能高效、稳定地运行。