Vue / 系统课时
注册动态路由
注册动态路由
本课解决“登录后菜单已经拿到,但地址栏仍无法进入对应页面”的问题。你将把后端权限菜单转换成 Vue Router 路由记录,并完成幂等注册、刷新恢复与退出清理,使菜单、路由和登录状态保持一致。
学习目标
- 将权限菜单安全映射为
RouteRecordRaw - 避免动态路由重复注册和组件路径失控
- 在刷新时恢复路由,在退出时彻底移除路由
明确动态路由的职责
静态路由应只保留登录页、403、404、后台布局等所有用户都需要的页面;业务页面由当前用户的权限菜单决定。后端返回的是菜单数据,前端负责把 path、name、组件标识和权限元信息转换为路由记录,再交给路由匹配器。
路由名称必须全局唯一且长期稳定,因为 hasRoute、removeRoute、页面缓存和标签页通常都会依赖它。组件标识不能直接拼接为任意动态导入路径,应先通过 import.meta.glob 建立可用页面白名单,避免菜单数据指向不存在或不应暴露的文件。

将菜单映射并幂等注册
下面是片段示例,依赖项目中已经存在名为 AdminLayout 的静态布局路由。菜单的 component 使用相对于 src/views 的路径,例如 system/user/index。
// src/router/dynamic-routes.ts
import { RouterView, type RouteRecordRaw, type Router } from 'vue-router'
export interface PermissionMenu {
path: string
name: string
component?: string
roles?: string[]
permissions?: string[]
children?: PermissionMenu[]
}
const viewModules = import.meta.glob('../views/**/*.vue')
const removeHandlers: Array<() => void> = []
function resolveView(component: string) {
const key = `../views/${component}.vue`
const loader = viewModules[key]
if (!loader) {
throw new Error(`未找到菜单组件:${component}`)
}
return loader
}
function menuToRoute(menu: PermissionMenu): RouteRecordRaw {
return {
path: menu.path,
name: menu.name,
component: menu.component ? resolveView(menu.component) : RouterView,
meta: {
roles: menu.roles ?? [],
permissions: menu.permissions ?? []
},
children: menu.children?.map(menuToRoute)
}
}
export function registerDynamicRoutes(
router: Router,
menus: PermissionMenu[]
): void {
for (const menu of menus) {
const route = menuToRoute(menu)
// 重复执行时跳过已存在的顶级路由,避免警告和匹配器污染。
if (route.name && router.hasRoute(route.name)) {
continue
}
removeHandlers.push(router.addRoute('AdminLayout', route))
}
}
export function clearDynamicRoutes(): void {
// 逆序移除可以先清理后注册的路由,减少父子关系残留。
while (removeHandlers.length > 0) {
removeHandlers.pop()?.()
}
}预期结果
首次调用 registerDynamicRoutes:当前用户的业务路由可被匹配
再次调用 registerDynamicRoutes:已存在的同名路由被跳过
调用 clearDynamicRoutes:本次会话注册的业务路由全部移除处理刷新恢复与退出清理
动态路由只存在于内存中,浏览器刷新后必须重新获取用户菜单并再次注册。注册发生在导航守卫中时,要在完成后用 replace 重新进入原地址,否则第一次匹配可能仍停留在 404 路由。
// src/router/install-dynamic-guard.ts
import type { Router } from 'vue-router'
import {
clearDynamicRoutes,
registerDynamicRoutes,
type PermissionMenu
} from './dynamic-routes'
export function installDynamicRouteGuard(
router: Router,
hasSession: () => boolean,
loadMenus: () => Promise<PermissionMenu[]>
) {
let ready = false
router.beforeEach(async (to) => {
if (!hasSession() || ready) {
return true
}
const menus = await loadMenus()
registerDynamicRoutes(router, menus)
ready = true
// 重新匹配刷新前的目标地址,并避免产生额外历史记录。
return { path: to.fullPath, replace: true }
})
return function resetDynamicRoutes() {
ready = false
clearDynamicRoutes()
}
}预期结果
刷新受保护页面:先恢复权限菜单和动态路由,再无闪烁地回到原地址
退出登录:调用 resetDynamicRoutes 后,旧账号的业务路由不再可访问退出流程应先清理动态路由和权限状态,再跳转登录页。若先跳转后清理,守卫可能在短时间内仍按旧权限放行。切换账号时也必须执行同样的重置流程,不能只覆盖令牌。
验收与常见问题
直接访问一个有权限的动态地址,页面应正常渲染;刷新后地址不变;连续触发菜单初始化不应出现重复路由警告;退出后再次输入原业务地址,应进入登录页或无权限页。
组件解析报错通常来自菜单中的组件路径与 src/views 实际文件不一致。页面始终进入 404,多半是注册完成后没有重新匹配当前地址。账号切换后看到旧菜单,则应检查退出流程是否同时清理了动态路由、菜单状态和页面缓存。