Vue 3 基于角色的路由守卫：实用模式

路由守卫能解决什么（以及不能做什么）

路由守卫有一个明确的工作：控制导航。它们决定某个人是否可以进入某个路由，或者在无法进入时把他们送到哪里。这能改善用户体验，但并不等同于安全性。

隐藏某个菜单项只是一个提示，不是授权。人们仍然可以手动输入 URL、刷新深层链接或打开书签。如果你唯一的保护是“按钮不可见”，那就没有保护。

当你希望应用在阻止不应显示的页面（比如管理后台、内部工具或基于角色的客户门户）时表现一致，守卫就很有用。

守卫能帮你：

• 在页面渲染前阻止访问
• 重定向到登录页或安全默认页
• 显示清晰的 401/403 页面而不是破碎的视图
• 避免意外的导航循环

守卫本身无法保护数据。如果 API 返回敏感数据到浏览器，用户仍然可以直接调用该端点（或在开发者工具中检查响应），即便页面被阻止。真正的授权也必须在服务器端执行。

理想目标是两端都覆盖：阻止页面和阻止数据。如果客服打开了仅限管理员的路由，守卫应该停止导航并显示“访问被拒绝”。同时，后台应该拒绝仅限管理员的 API 调用，这样敏感数据永远不会被返回。

选择简单的角色与权限模型

当你从一长串角色开始时，访问控制会变得混乱。从人们真正理解的一小组开始，只有在确有痛点时再添加更细的权限。

一个实用的划分是：

• 角色描述某人在应用中的身份。
• 权限描述他们可以做什么。

对于大多数内部工具，三种角色已经能覆盖许多场景：

• admin：管理用户和设置，查看所有数据
• support：处理客户记录和回复，但不能管理系统设置
• viewer：经审批的界面只读访问

尽早决定角色从何而来。Token 声明（如 JWT）对守卫来说很快但可能会过期直到刷新。应用启动时拉取用户档案总是最新的，但守卫必须等到该请求完成。

还要清晰地区分路由类型：公共路由（对所有人开放）、需认证路由（需要会话）和受限路由（需要某个角色或权限）。

使用路由 meta 定义访问规则

最清晰的方式是把访问声明写在路由本身。Vue Router 允许你在每个路由记录上附加一个 meta 对象，供守卫在稍后读取。这让规则靠近受保护的页面。

选择一个简单的 meta 结构并在应用中坚持使用。

const routes = [
  {
    path: "/admin",
    component: () => import("@/pages/AdminLayout.vue"),
    meta: { requiresAuth: true, roles: ["admin"] },
    children: [
      {
        path: "users",
        component: () => import("@/pages/AdminUsers.vue"),
        // inherits requiresAuth + roles from parent
      },
      {
        path: "audit",
        component: () => import("@/pages/AdminAudit.vue"),
        meta: { permissions: ["audit:read"] },
      },
    ],
  },
  {
    path: "/tickets",
    component: () => import("@/pages/Tickets.vue"),
    meta: { requiresAuth: true, permissions: ["tickets:read"], readOnly: true },
  },
]

对于嵌套路由，决定规则如何合并。在大多数应用中，子路由应该继承父级要求。在你的守卫中，检查每个匹配的路由记录（而不只是 to.meta），以免跳过父级规则。

一个能节省时间的细节是：区分“可以查看”和“可以编辑”。一个路由可能对 support 和 admin 可见，但对 support 的编辑应该被禁用。readOnly: true 标记可以驱动 UI 行为（禁用操作，隐藏破坏性按钮），但不能把它当作安全措施。

准备好认证状态以让守卫表现可靠

大多数守卫错误来自一个问题：守卫在应用知道当前用户是谁之前就运行了。

把认证视为一个小的状态机，并让它成为唯一的事实来源。你需要三个清晰的状态：

• unknown：应用刚启动，尚未检查会话
• logged out：会话检查完成，没有有效用户
• logged in：用户已加载，角色/权限可用

规则是：不要在认证为 unknown 时读取角色。那样会导致短暂显示受保护界面或意外重定向到登录。

决定会话刷新策略

选择一种刷新策略并保持可预测（例如：读取 token，调用 “who am I” 接口，设置用户）。

一个稳定的模式看起来像：

• 在应用加载时，把 auth 设为 unknown 并启动一次刷新请求
• 刷新完成（或超时）后再解析守卫
• 在内存中缓存用户，而不要放在路由 meta 中
• 失败时把 auth 设为 logged out
• 暴露一个 ready promise（或类似机制）供守卫等待

有了这些后，守卫逻辑保持简单：等待 auth 就绪，然后决定是否允许访问。

逐步实现路由级授权

一个干净的做法是把大多数规则放在一个全局守卫里，只有在路由确实需要特殊逻辑时才使用每路由的守卫。

1) 添加一个全局 beforeEach 守卫

// router/index.js
router.beforeEach(async (to) => {
  const auth = useAuthStore()

  // Step 2: wait for auth initialization when needed
  if (!auth.ready) await auth.init()

  // Step 3: check authentication, then roles/permissions
  if (to.meta.requiresAuth && !auth.isAuthenticated) {
    return { name: 'login', query: { redirect: to.fullPath } }
  }

  const roles = to.meta.roles
  if (roles && roles.length > 0 && !roles.includes(auth.userRole)) {
    return { name: 'forbidden' } // 403
  }

  // Step 4: allow navigation
  return true
})

这涵盖了大多数情况，避免把检查散落在组件里。

何时 beforeEnter 更合适

当规则是真正路由特定并且依赖 to.params.id 时使用 beforeEnter，比如“只有工单所有者可以打开此页面”。保持逻辑简短并重用相同的 auth 存储，这样行为一致。

安全重定向而不打开漏洞

如果你把重定向视为可信，它们可能悄悄破坏你的访问控制。

常见模式是：未登录用户被发送到登录页，并附带 returnTo 查询参数。登录后读取它并导航到那里。风险在于开放重定向（把用户送到意外的地方）和循环。

保持行为简单：

• 未登录用户去 Login，returnTo 设置为当前路径。
• 已登录但无权限的用户去专门的 Forbidden 页面（而不是 Login）。
• 仅允许你识别的内部 returnTo 值。
• 增加一个循环检查，避免重定向到相同地点。

const allowedReturnTo = (to) => {
  if (!to || typeof to !== 'string') return null
  if (!to.startsWith('/')) return null
  // optional: only allow known prefixes
  if (!['/app', '/admin', '/tickets'].some(p => to.startsWith(p))) return null
  return to
}

router.beforeEach((to) => {
  if (!auth.isReady) return false

  if (!auth.isLoggedIn && to.name !== 'Login') {
    return { name: 'Login', query: { returnTo: to.fullPath } }
  }

  if (auth.isLoggedIn && !canAccess(to, auth.user) && to.name !== 'Forbidden') {
    return { name: 'Forbidden' }
  }
})

在导航期间避免泄露受限数据

最容易泄露的是在你确认用户是否有权限前就加载数据。

在 Vue 中，这通常发生在页面在 setup() 中获取数据，而路由守卫稍后才运行。即便用户被重定向，响应仍可能写入共享存储或短暂显示在屏幕上。

更安全的规则是：先授权，再加载。

// router guard: authorize before entering the route
router.beforeEach(async (to) => {
  await auth.ready() // ensure roles are known
  const required = to.meta.requiredRole
  if (required && !auth.hasRole(required)) {
    return { name: 'forbidden' }
  }
})

还要注意在快速导航时的延迟请求。取消请求（例如用 AbortController）或通过检查请求 id 忽略迟到的响应。

缓存是另一个常见陷阱。如果你在全局存储中保存了“最近加载的客户记录”，管理员专属的响应可能在后来显示给非管理员。按用户 id 和角色为缓存加键，或在登出（或角色变更）时清除敏感模块。

一些良好习惯能防止大多数泄露：

• 在确认授权前不要请求敏感数据。
• 按用户和角色对缓存数据加键，或把缓存限定在页面局部。
• 在路由变化时取消或忽略正在进行的请求。

友好的回退页：401、403 和 404

“否”的路径和“是”的路径同样重要。良好的回退页面能让用户保持方向感并减少工单。

401：需要登录（未认证）

当用户未登录时使用 401。信息保持简洁：他们需要登录才能继续。如果你支持登录后返回原页面，请验证返回路径，确保它不能指向应用外部。

403：访问被拒绝（已认证但无权限）

当用户已登录但缺少权限时使用 403。措辞保持中性，避免泄露敏感细节。

一个稳妥的 403 页面通常包含一个清晰的标题（“访问被拒绝”）、一句话说明，以及一个安全的下一步（返回仪表盘、联系管理员、如果支持则切换账户）。

404：未找到

把 404 与 401/403 分开处理。否则人们会以为页面不存在是因为权限不足。

常见会破坏访问控制的错误

大多数访问控制漏洞是简单的逻辑失误，表现为重定向循环、短暂显示错误页面或用户被卡住。

常见原因包括：

• 把隐藏的 UI 当作“安全”。始终在路由和 API 层强制角色检查。
• 在登出/登录后从过期状态读取角色。
• 把未授权用户重定向到另一个受保护的路由（导致循环）。
• 忽视刷新时“认证仍在加载”的时刻。
• 混淆 401 和 403，导致用户困惑。

一个真实例子：客服在共享电脑上登出，之后管理员登录。如果守卫在新会话确认前读取了缓存角色，你可能会错误地阻止管理员，或者更糟地，短暂允许本不应该的访问。

上线前的快速检查清单

做一次短测，关注访问控制通常出问题的时刻：网络慢、会话过期和书签 URL。

• 每个受保护路由都有明确的 meta 要求。
• 守卫在认证加载时处理好，不会短暂显示受保护 UI。
• 未授权用户落到清晰的 403 页面（而不是混乱的主页跳转）。
• 任何“返回”重定向都会被验证并且不会造成循环。
• 敏感 API 调用仅在授权确认后才执行。

然后完整测试一个场景：在未登录状态下在新标签页打开一个受保护 URL，作为普通用户登录，确认你要么到达目标页面（如果被允许），要么看到带有下一步的清晰 403。

示例：小型 Web 应用中的 support 与 admin 访问

假设一个工单系统，仅有两个角色：support 和 admin。Support 可以读取并回复工单。Admin 也能这么做，并且还可以管理计费和公司设置。

• /tickets/:id 允许 support 和 admin
• /settings/billing 仅允许 admin

现在一个常见场景：客服从旧书签打开了深层链接 /settings/billing。守卫应该在页面加载前检查路由 meta 并阻止导航。因为用户已登录但缺少角色，他们应该落到安全的回退页（403）。

两条信息很重要：

• 需要登录（401）： “请登录以继续。”
• 访问被拒绝（403）： “您无权访问计费设置。”

绝不可发生的事情是：计费组件被挂载，或计费数据即使短暂地被请求到。

会话中角色变更是另一个边缘情形。如果有人在会话中被提升或降级，不要只依赖菜单。导航时重新检查角色，并决定当某个页面不再被允许时如何处理：在配置变更时刷新认证状态，或检测角色变化并重定向离开不再允许的页面。

后续步骤：保持访问规则可维护

守卫一旦工作，风险在于规则漂移：新路由发布却没有 meta，角色被重命名，规则不一致。

把规则变成一个小测试计划，每次添加路由时运行：

• 作为访客：打开受保护路由，确认你被重定向到登录且没有看到部分内容。
• 作为普通用户：打开一个你不该访问的页面，确认你得到清晰的 403。
• 作为管理员：尝试从地址栏打开深层链接。
• 对每个角色：在受保护路由上刷新并确认结果稳定。

如果想要额外的安全网，可以添加一个仅开发环境可见的视图或控制台输出，列出路由及其 meta 要求，这样缺失的规则会立即显现。

如果你正在使用 AppMaster (appmaster.io) 构建内部工具或门户，方法相同：在 Vue3 UI 中把路由守卫聚焦于导航，在后端逻辑和数据层强制权限。

选择一个改进并端到端实现它：收紧数据请求的门控、改进 403 页面，或锁定重定向处理。小修复能阻止大多数真实世界的访问问题。