Vue与React路由守卫通用实现指南解决前端权限管理难题

路由守卫是前端开发中实现页面访问控制与权限管理的核心技术。听起来似乎只是简单的权限拦截，但在实际开发中，开发者常会遇到一系列典型问题：未登录用户如何被有效拦截？不同用户角色如何实现精准的页面隔离？页面跳转时如何确保数据预加载，避免白屏？这些问题处理不当，直接影响应用的安全性与用户体验。

本文将为您提供一套可直接复用的路由守卫封装方案，深入解析其在 Vue 2、Vue 3 及 React 框架中的实现逻辑，并帮助您规避四个最常见的开发陷阱。

一、路由守卫的核心作用与价值

无论是 Vue Router 还是 React Router，路由守卫的核心职责是充当应用的“安全网关”，精确管理页面导航的访问权限与生命周期钩子。它主要解决以下关键场景：

• 身份认证拦截：阻止未登录用户访问需要认证的页面，如个人中心、订单管理等。
• 角色权限控制：根据用户角色（如普通用户、管理员）动态控制可访问的路由与菜单。
• 导航确认：在用户离开当前页面（如表单编辑页）前进行二次确认，防止数据丢失。
• 数据预取与状态管理：在进入目标页面前预先加载必要数据，优化页面渲染体验，减少等待时间。

简而言之，路由守卫是构建前端权限体系的中枢。尽管不同框架的 API 设计存在差异，但其底层逻辑高度一致。接下来，我们将分别探讨在主流框架中如何实现一套健壮、可维护的路由守卫方案。

二、Vue 2 / Vue 3 路由守卫完整封装指南

在 Vue 生态中，路由守卫主要分为全局守卫、路由独享守卫和组件内守卫三类。对于大多数中后台管理系统，全局前置守卫足以覆盖核心的权限校验需求。

1. Vue 3 + 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;

在登录页面组件中，登录成功后需处理重定向逻辑：

2. Vue 2 + Vue Router 3 兼容方案

逻辑与 Vue 3 版本完全一致，仅语法存在细微差异：

// router/index.js（Vue2）
import Vue from 'vue';
import Router from 'vue-router';
import { getStorage } from '@/utils/storage';

Vue.use(Router);

const routes = [
  // 路由配置与 Vue 3 版本一致
  { 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 取消了传统的全局守卫 API（如 onEnter、beforeEach），转而采用更符合 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: 存在角色限制，但当前用户角色不匹配，重定向至首页
  if (role && role !== userRole) {
    return ;
  }

  // 情况3: 所有检查通过，渲染子路由（Outlet 相当于 Vue 中的 router-view）
  return ;
};

2. 路由配置集成（router/index.jsx）

在路由配置中，像使用普通组件一样引入权限守卫：

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: 
  },
  {
    path: '/login',
    element: 
  },
  // 需要权限的路由：使用 PrivateRoute 组件包裹
  {
    path: '/user',
    element: , // 限制为普通用户角色
    children: [
      { path: '', element:  } // 子路由，对应 Outlet 渲染位置
    ]
  },
  // 管理员专属路由
  {
    path: '/admin',
    element: , // 仅管理员可访问
    children: [
      { path: '', element:  }
    ]
  },
  // 404 页面兜底
  {
    path: '*',
    element: 
  }
]);

export default router;

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 登录页面重定向处理

登录成功后，需实现重定向至用户原本意图访问的页面：

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;

四、实战避坑指南：四个高频问题与解决方案

即使代码逻辑正确，一些细节疏忽仍可能导致功能异常。以下是四个新手开发者最容易遇到的典型问题及其解决方案。

问题一：Vue 路由守卫中遗漏 next() 调用，导致页面导航卡死
这是最常见的错误。在 beforeEach 守卫中，每个逻辑分支都必须调用一次 next() 函数，否则路由将停滞不前。务必确保在每个条件判断后都执行 next() 或 next(path) 进行导航控制。

问题二：在 React Router 6 中误用旧版本 API 编写守卫逻辑
React Router 6 是一个重大更新，它移除了 onEnter、beforeEach 等传统守卫方法。若从旧项目迁移或参考过时教程，极易在此处出错。正确的做法是封装一个权限校验组件来包裹需要保护的路由。

问题三：未实现登录后重定向至原始目标页面，导致用户体验断裂
用户意图访问受保护页面（如 /user）时被拦截至登录页。登录成功后，若直接跳转至首页，用户需要重新导航，体验不佳。解决方案是在跳转登录页时，通过查询参数（如 redirect）携带原始目标地址，登录成功后再进行定向跳转。

问题四：权限校验不严谨，仅验证登录状态而忽略角色控制，导致越权访问
仅检查用户是否登录，而不验证其具体角色，是权限系统的重大安全隐患。普通用户可能通过直接输入 URL 访问管理员界面。因此，必须在路由定义中明确角色要求（Vue 的 meta 字段，React 的组件属性），并在守卫逻辑中进行严格匹配。

五、进阶应用：路由守卫高级场景实践

掌握基础权限控制后，路由守卫还可用于处理更复杂的交互场景。

1. 表单未保存确认提示（Vue 组件内守卫）

在用户尝试离开未保存的表单页面时，提供友好的确认提示：

2. 全局页面加载状态管理（集成至全局守卫）

在页面跳转前后，控制全局加载动画的显示与隐藏：

// 在 Vue 3 全局守卫中集成 Loading 状态管理
import { ref } from 'vue';
export const isLoading = ref(false);

router.beforeEach((to, from, next) => {
  isLoading.value = true; // 导航开始，显示加载动画
  // ... 此处执行原有的权限校验逻辑
  next();
});

router.afterEach(() => {
  // 导航完成，延迟隐藏加载动画（使页面过渡更平滑）
  setTimeout(() => {
    isLoading.value = false;
  }, 300);
});

六、核心总结

路由守卫是实现前端精细化权限控制与导航管理的标准化方案。无论底层采用 Vue Router 还是 React Router，其核心任务始终围绕三点展开：身份验证（登录状态校验）、权限校验（用户角色匹配）与导航控制（页面跳转管理）。

本文提供的封装代码已覆盖绝大多数业务场景。您可直接将其复制到项目中，并根据实际业务需求微调路由配置与角色逻辑，即可快速搭建起一套可靠的前端权限防线。牢记并规避上述四个常见问题，您的路由守卫将运行得更加稳定与高效。