Vue Vben Admin 路由与菜单完全指南核心路由、静态路由、动态路由与 meta 配置详解【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin本篇指南以 Vue Vben Admin 仓库中的官方文档 docs/src/en/guide/essentials/route.md 为基础骨架结合仓库内playground/src/router/routes/、packages/utils/src/helpers/、packages/effects/hooks/src/use-refresh.ts等源码实现展开系统讲解框架内置的路由体系核心路由/静态路由/动态路由、路由定义规范、如何新增页面、全部meta配置项、路由刷新方法以及标签页与路由控制机制。读完本文你将能独立为 Vben Admin 项目添加任意层级的业务页面并熟练运用authority权限控制、keepAlive缓存、iframeSrc内嵌、link外链、badge徽标、affixTab固定标签页等高频能力。路由类型核心路由、静态路由与动态路由在 Vben Admin 中框架提供了一套基础路由系统并根据路由文件自动生成对应的菜单结构。整套路由体系分为三种类型各自承担不同的职责核心路由Core Routes框架内置的路由包含根路由、登录路由、404 路由等用于支撑框架基础功能配置位于应用下的src/router/routes/core目录。静态路由Static Routes在项目启动时就已确定的路由配置位于应用下的src/router/routes/static目录需自行创建。动态路由Dynamic Routes一般在用户登录后根据用户权限动态生成的路由配置位于应用下的src/router/routes/modules目录。静态路由与动态路由都会经过权限控制可通过配置路由meta属性中的authority字段来控制具体实现可参考 playground/src/router/routes/modules/demos.ts 中AccessDemos路由组该组下分别配置了authority: [super]、authority: [admin]、authority: [user]及menuVisibleWithForbidden: true等多种权限场景。核心路由核心路由是框架内置、必须存在的路由。在 playground 应用中核心路由配置于 playground/src/router/routes/core.ts主要包含根路由Rootpath: /使用BasicLayout基础布局作为所有页面的父级容器子级路由无需再配置 BasicLayout其redirect指向preferences.app.defaultHomePath默认首页路径。源码注释明确标注“此路由必须存在且不应修改”。认证路由Authenticationpath: /auth使用AuthPageLayout其下包含login、code-login、qrcode-login、forget-password、register等认证相关子路由默认重定向到LOGIN_PATH。404 兜底路由FallbackNotFoundpath: /:path(.*)*捕获所有未匹配路径meta中设置了hideInMenu: true、hideInTab: true、hideInBreadcrumb: true。[!TIP] 核心路由主要用于框架基础功能不建议将业务相关路由放入核心路由业务路由应放在静态路由或动态路由中。在 playground/src/router/routes/index.ts 中核心路由、外部路由与 404 兜底路由被合并为routes无需走权限验证同时通过traverseTreeValues提取出coreRouteNames用于在路由守卫中跳过核心路由的权限拦截/** 路由列表由基本路由、外部路由和404兜底路由组成 * 无需走权限验证会一直显示在菜单中 */ const routes: RouteRecordRaw[] [ ...coreRoutes, ...externalRoutes, fallbackNotFoundRoute, ]; /** 基本路由列表这些路由不需要进入权限拦截 */ const coreRouteNames traverseTreeValues(coreRoutes, (route) route.name); /** 有权限校验的路由列表包含动态路由和静态路由 */ const accessRoutes [...dynamicRoutes, ...staticRoutes];静态路由与动态路由的加载方式静态路由的配置同样位于应用下的src/router/routes/index目录如 playground/src/router/routes/index.ts通过import.meta.glob批量加载const dynamicRouteFiles import.meta.glob(./modules/**/*.ts, { eager: true, }); // 有需要可以自行打开注释并创建文件夹 // const externalRouteFiles import.meta.glob(./external/**/*.ts, { eager: true }); // const staticRouteFiles import.meta.glob(./static/**/*.ts, { eager: true }); /** 动态路由 */ const dynamicRoutes: RouteRecordRaw[] mergeRouteModules(dynamicRouteFiles); /** 外部路由列表访问这些页面可以不需要Layout可能用于内嵌在别的系统(不会显示在菜单中) */ // const externalRoutes: RouteRecordRaw[] mergeRouteModules(externalRouteFiles); // const staticRoutes: RouteRecordRaw[] mergeRouteModules(staticRouteFiles); const staticRoutes: RouteRecordRaw[] []; const externalRoutes: RouteRecordRaw[] [];关键点说明import.meta.glob(./modules/**/*.ts, { eager: true })利用 Vite 的 glob 导入能力自动收集modules目录下所有.ts路由文件无需手动逐个注册。mergeRouteModules该工具函数位于 packages/utils/src/helpers/merge-route-modules.ts其实现是遍历所有路由模块对象将每个模块的default导出RouteRecordRaw[]展开合并为一个数组function mergeRouteModules( routeModules: Recordstring, unknown, ): RouteRecordRaw[] { const mergedRoutes: RouteRecordRaw[] []; for (const routeModule of Object.values(routeModules)) { const moduleRoutes (routeModule as RouteModuleType)?.default ?? []; mergedRoutes.push(...moduleRoutes); } return mergedRoutes; }静态/外部路由默认关闭源码中staticRoutes与externalRoutes默认均为空数组需要时取消注释 glob 并创建对应目录即可。外部路由external用于无需 Layout 包裹、可直接访问的页面适合被其他系统内嵌的场景且不会显示在菜单中。[!TIP] 权限控制是通过路由meta属性中的authority字段控制的。如果页面项目不需要权限控制可以不设置authority字段。路由定义二级路由与多级路由静态路由与动态路由的配置方式完全一致均符合 Vue Router 的路由配置格式。下面分别给出二级与多级路由的完整示例动态路由文件位于应用src/router/routes/modules目录如 playground/src/router/routes/modules/demos.ts、playground/src/router/routes/modules/dashboard.ts 等。二级路由[!TIP]只有顶级路由的path需要以/开头写在children中的子路由请使用相对路径片段例如about、menu1。当父级路由未显式配置redirect时框架会自动补全为第一个子路由的重定向这依赖子路由使用相对路径。import type { RouteRecordRaw } from vue-router; import { VBEN_LOGO_URL } from vben/constants; import { $t } from #/locales; const routes: RouteRecordRaw[] [ { meta: { badgeType: dot, badgeVariants: destructive, icon: VBEN_LOGO_URL, order: 9999, title: $t(page.vben.title), }, name: VbenProject, path: /vben-admin, children: [ { name: VbenAbout, path: about, component: () import(#/views/_core/about/index.vue), meta: { badgeType: dot, badgeVariants: destructive, icon: lucide:copyright, title: $t(page.vben.about), }, }, ], }, ]; export default routes;要点解析name必须唯一且建议使用有意义的驼峰命名它是路由的稳定标识也被generateMenus等工具用于路径映射。component使用动态导入() import(#/views/...)#是应用内的路径别名指向src目录Vite 会据此做代码分割与按需加载。title配合国际化通过$t(page.vben.title)引用 packages/locales/src/langs/ 中的文案键实现菜单与标签页标题的多语言。多级路由[!TIP]多级路由同样遵循“顶级绝对路径、子级相对路径”的组织方式避免在children中重复写完整路径。多级路由的父级路由不需要设置component属性只需设置children属性除非确实需要在父路由下嵌套展示内容。大多数情况下父级路由的redirect属性无需指定默认指向第一个子路由。以下是一个包含 4 层嵌套的多级路由示例与文档示例一致仓库中 playground/src/router/routes/modules/demos.ts 的NestedDemos路由组即为该结构的真实实现import type { RouteRecordRaw } from vue-router; import { $t } from #/locales; const routes: RouteRecordRaw[] [ { meta: { icon: ic:baseline-view-in-ar, keepAlive: true, order: 1000, title: $t(demos.title), }, name: Demos, path: /demos, children: [ // 嵌套菜单 { meta: { icon: ic:round-menu, title: $t(demos.nested.title), }, name: NestedDemos, path: nested, children: [ { name: Menu1Demo, path: menu1, component: () import(#/views/demos/nested/menu-1.vue), meta: { icon: ic:round-menu, keepAlive: true, title: $t(demos.nested.menu1), }, }, { name: Menu2Demo, path: menu2, meta: { icon: ic:round-menu, keepAlive: true, title: $t(demos.nested.menu2), }, children: [ { name: Menu21Demo, path: menu2-1, component: () import(#/views/demos/nested/menu-2-1.vue), meta: { icon: ic:round-menu, keepAlive: true, title: $t(demos.nested.menu2_1), }, }, ], }, { name: Menu3Demo, path: menu3, meta: { icon: ic:round-menu, title: $t(demos.nested.menu3), }, children: [ { name: Menu31Demo, path: menu3-1, component: () import(#/views/demos/nested/menu-3-1.vue), meta: { icon: ic:round-menu, keepAlive: true, title: $t(demos.nested.menu3_1), }, }, { name: Menu32Demo, path: menu3-2, meta: { icon: ic:round-menu, title: $t(demos.nested.menu3_2), }, children: [ { name: Menu321Demo, path: menu3-2-1, component: () import(#/views/demos/nested/menu-3-2-1.vue), meta: { icon: ic:round-menu, keepAlive: true, title: $t(demos.nested.menu3_2_1), }, }, ], }, ], }, ], }, ], }, ]; export default routes;多级路由的核心约定中间层级的路由如NestedDemos、Menu2Demo、Menu3Demo、Menu32Demo只写meta、name、path、children不写component——它们只是菜单分组容器由框架自动生成层级结构。只有真正的叶子路由如Menu1Demo、Menu21Demo、Menu321Demo需要配置component。每一级的path都是相对片段最终完整路径由父级拼接而成例如Menu321Demo的完整路径为/demos/nested/menu3/menu3-2/menu3-2-1。新增一个页面新增页面只需两步添加一个路由添加对应的页面组件。添加路由在对应的路由文件中如modules/dashboard.ts添加一个路由对象import type { RouteRecordRaw } from vue-router; import { VBEN_LOGO_URL } from vben/constants; import { $t } from #/locales; const routes: RouteRecordRaw[] [ { meta: { icon: mdi:home, title: $t(page.home.title), }, name: Home, path: /home, children: [ { name: HomeIndex, path: index, component: () import(#/views/home/index.vue), meta: { icon: mdi:home, title: $t(page.home.index), }, }, ], }, ]; export default routes;注意title对应的多语言键如page.home.title需要同步在 packages/locales/src/langs/ 下的各语言 JSON 文件中添加否则菜单会显示为空的 key 字符串。添加页面组件在#/views/home/下新建index.vue文件template div h1home page/h1 /div /template验证至此页面添加完成启动应用后访问http://localhost:5555/home/index即可看到对应页面端口 5555 为 playground 应用的默认开发端口实际以各应用的vite.config.ts配置为准。由于路由文件通过import.meta.glob自动收集新添加的路由会立即被框架识别并渲染到菜单中无需手动注册。路由配置meta 属性详解路由配置项主要集中在路由对象的meta属性中。以类型定义的形式来看完整字段如下。该接口定义位于 packages/core/base/typings/src/vue-router.d.ts是全局路由元信息的权威来源interface RouteMeta { /** 激活图标菜单 */ activeIcon?: string; /** 当前激活的菜单有时候不想激活现有菜单需要激活父级菜单时使用 */ activePath?: string; /** 是否使用 activePath 对应的路由层级生成面包屑 default false */ breadcrumbUseActivePath?: boolean; /** 是否固定标签页 default false */ affixTab?: boolean; /** 固定标签页的顺序 default 0 */ affixTabOrder?: number; /** 需要特定的角色标识才可以访问 default [] */ authority?: string[]; /** 徽标 */ badge?: string; /** 徽标类型 */ badgeType?: dot | normal; /** 徽标颜色 */ badgeVariants?: default | destructive | primary | success | warning | string; /** 路由对应dom是否缓存起来 */ domCached?: boolean; /** 路由的完整路径作为key默认true */ fullPathKey?: boolean; /** 当前路由的子级在菜单中不展现 default false */ hideChildrenInMenu?: boolean; /** 当前路由在面包屑中不展现 default false */ hideInBreadcrumb?: boolean; /** 当前路由在菜单中不展现 default false */ hideInMenu?: boolean; /** 当前路由在标签页不展现 default false */ hideInTab?: boolean; /** 图标菜单/tab */ icon?: Component | string; /** iframe 地址 */ iframeSrc?: string; /** 忽略权限直接可以访问 default false */ ignoreAccess?: boolean; /** 开启KeepAlive缓存 */ keepAlive?: boolean; /** 外链-跳转路径 */ link?: string; /** 路由是否已经加载过 */ loaded?: boolean; /** 标签页最大打开数量 default -1 */ maxNumOfOpenTab?: number; /** 菜单可以看到但是访问会被重定向到403 */ menuVisibleWithForbidden?: boolean; /** 不使用基础布局仅在顶级生效 */ noBasicLayout?: boolean; /** 在新窗口打开 */ openInNewWindow?: boolean; /** 用于路由-菜单排序 */ order?: number; /** 菜单所携带的参数 */ query?: Recordable; /** 标题名称 */ title: string; }下面对照该类型定义逐项讲解常用配置项。title类型string| 默认值用于配置页面的标题会在菜单和标签页中显示一般配合国际化使用$t()。icon类型string| 默认值用于配置页面的图标会在菜单和标签页中显示。一般配合图标库使用如lucide:copyright、mdi:home、ic:round-menu等 Iconify 风格图标名如果是http链接如图片 URL会自动加载图片。在 playground 的VbenProject路由中icon直接使用了vben/constants导出的VBEN_LOGO_URL图片链接即属于此种用法。activeIcon类型string| 默认值用于配置页面的激活图标会在菜单中显示。一般配合图标库使用如果是http链接会自动加载图片。典型场景见 playground/src/router/routes/modules/demos.ts 中的ActiveIconDemos路由组常态图标为bi:radioactive激活时切换为fluent-emoji:radioactive。keepAlive类型boolean| 默认值false用于配置页面是否开启缓存。开启后页面会被缓存、切换回来不会重新加载仅在标签页Tab启用时有效。对于列表页等需要保留滚动位置与表单状态的页面非常实用。hideInMenu类型boolean| 默认值false用于配置页面是否在菜单中隐藏。设置为true后页面不会出现在菜单里但仍可通过 URL 直接访问。典型用途详情页。例如 playground/src/router/routes/modules/demos.ts 中FeatureTabDetailDemopath: detail/:id就配置了hideInMenu: true。hideInTab类型boolean| 默认值false用于配置页面是否在标签页中隐藏隐藏后不会在标签页中显示。hideInBreadcrumb类型boolean| 默认值false用于配置页面是否在面包屑中隐藏隐藏后不会在面包屑中显示。hideChildrenInMenu类型boolean| 默认值false用于配置当前路由的子级是否在菜单中隐藏。当父路由需要作为可点击的菜单项、又不希望展示其子菜单时使用。从 packages/utils/src/helpers/generate-menus.ts 的实现可以看到其底层行为// 处理子菜单 const resultChildren hideChildrenInMenu ? [] : ((children as MenuRecordRaw[]) ?? []); // 确定最终路径 const resultPath hideChildrenInMenu ? redirect || path : link || path;即当hideChildrenInMenu: true时子菜单数组会被清空且菜单点击路径取redirect || path若配置了redirect则跳转到该重定向地址。实际示例见demos.ts中的HideChildrenInMenuParentDemo路由组。authority类型string[]| 默认值[]用于配置页面的权限角色标识数组只有拥有对应角色的用户才能访问页面不配置则不需要权限。这是路由级权限控制的核心字段。示例来自 playground/src/router/routes/modules/demos.ts{ name: AccessAdminVisibleDemo, path: admin-visible, component: () import(#/views/demos/access/admin-visible.vue), meta: { authority: [admin], icon: mdi:button-cursor, title: $t(demos.access.adminVisible), }, }权限的实际判定在 playground/src/router/access.ts 与 packages/effects/access/src/ 中完成应用通过generateAccessible来自vben/access结合当前用户的roles过滤出accessibleMenus与accessibleRoutes。配套的前端权限组件与指令可参考 packages/effects/access/src/access-control.vue、packages/effects/access/src/directive.ts其单元测试见 packages/effects/access/src/tests/accessible.test.ts。badge / badgeType / badgeVariantsbadge类型string默认。配置菜单上显示的徽标文本如10、Hot。badgeType类型dot | normal默认normal。dot为小红点normal为文本。badgeVariants类型default | destructive | primary | success | warning | string默认success。配置徽标颜色。实际示例同样在demos.ts的BadgeDemos路由组badge: 10显示文本徽标、badgeType: dot显示红点、badgeVariants: destructive设置红色高亮。activePath类型string| 默认值配置当前激活的菜单。当页面本身没有显示在菜单内如hideInMenu: true的详情页但又希望激活某个父级菜单时使用。示例见demos.ts中的FeatureTabDetailDemoactivePath: /demos/features/tabs访问该详情页时侧边菜单会高亮“功能”菜单。breadcrumbUseActivePath类型boolean| 默认值false设置为true时面包屑会使用activePath对应的路由层级补充当前路由的匹配记录。适用于详情页等未嵌套在目标菜单路由下、但仍需要展示完整面包屑层级的页面。affixTab / affixTabOrderaffixTab类型boolean默认false。配置页面是否固定在标签页中固定后该标签不可关闭。affixTabOrder类型number默认0。配置固定标签页的排序采用升序排列。常用于首页、工作台等希望常驻标签栏的页面。iframeSrc类型string| 默认值配置内嵌页面的iframe地址设置后会在当前页面内嵌对应的外部系统。使用该字段时组件通常指向框架提供的IFrameView从#/layouts导入。示例见demos.ts的VueDocumentDemo{ name: VueDocumentDemo, path: vue-document, component: IFrameView, meta: { icon: logos:vue, iframeSrc: https://cn.vuejs.org/, keepAlive: true, title: Vue, }, }ignoreAccess类型boolean| 默认值false配置页面是否忽略权限校验、直接可访问。从 playground/src/router/guard.ts 的守卫逻辑可以看到当用户没有accessToken时若to.meta.ignoreAccess为true则放行否则跳转登录页// accessToken 检查 if (!accessStore.accessToken) { // 明确声明忽略权限访问权限则可以访问 if (to.meta.ignoreAccess) { return true; } // 没有访问权限跳转登录页面 ... }link类型string| 默认值配置外链跳转路径会在新窗口打开。示例见demos.ts的ViteDemolink: https://vitejs.dev/。同时从generateMenus源码可以看到当配置了link后菜单项的最终路径取link || path。maxNumOfOpenTab类型number| 默认值-1配置标签页最大打开数量。设置后在打开新标签页时会自动关闭最早打开的标签页仅在打开同名标签页时生效。示例见demos.ts的FeatureTabDetailDemomaxNumOfOpenTab: 3配合hideInMenu与activePath演示“同一路由多标签页”场景。menuVisibleWithForbidden类型boolean| 默认值false配置页面在菜单中可见但访问时被重定向到 403页面。示例见demos.ts的AccessMenuVisible403Demoauthority: [no-body]且menuVisibleWithForbidden: true普通用户能看到该菜单项点击访问则进入 403。在 playground/src/router/access.ts 中通过forbiddenComponent#/views/_core/fallback/forbidden.vue接管了此类无权限路由的渲染。openInNewWindow类型boolean| 默认值false设置为true时页面会在新窗口打开。示例见demos.ts的NewWindowDemo。order类型number| 默认值0用于配置页面排序路由 → 菜单排序。[!NOTE] 排序仅对一级菜单有效二级菜单的排序需要在对应的一级菜单中按代码书写顺序设置。generateMenus底层使用sortTree按order升序排列并做了order缺省时按999兜底处理避免order 0被替换成999的排序问题见 packages/utils/src/helpers/generate-menus.ts。query类型Recordable| 默认值{}配置页面菜单携带的参数会在菜单跳转时传递给页面。示例见demos.ts的MenuQueryDemoquery: { id: 1 }点击菜单进入页面后可通过路由query读取到id 1。noBasicLayout类型boolean| 默认值false配置当前路由不使用基础布局仅在顶级路由生效。默认情况下所有路由都会被包裹在基础布局中包含顶部、侧边等导航部件若页面不需要这些部件如某些纯展示/落地页可设置noBasicLayout: true。domCached类型boolean| 默认值false配置当前路由是否将路由对应的DOM 元素缓存起来。对于一些复杂页面切换 Tab 时浏览器的回流/重绘会导致卡顿domCached: true可解决该问题但有代价内存占用升高Vue 的部分生命周期不会触发。该字段在demos.ts的AccessPageControlDemo中有实际使用domCached: true。loaded类型boolean框架内部使用表示路由是否已经加载过由路由守卫自动维护一般无需手动配置。从 playground/src/router/guard.ts 可以看到setupCommonGuard通过loadedPaths集合记录已访问路径并在beforeEach中写入to.meta.loaded用于控制页面切换动画与加载进度条是否重复执行。菜单如何从路由自动生成理解“根据路由文件自动生成菜单”的机制有助于更好地设计路由。核心实现位于 packages/utils/src/helpers/generate-menus.ts其流程可概括为构建路径映射将router.getRoutes()得到的name → path映射表用于把路由的name解析为最终路径finalRoutesMap[route.name] ?? route.path保证多层相对路径能解析出完整路径。映射菜单字段从路由的meta中提取title、icon、activeIcon、badge、badgeType、badgeVariants、order、link、query等字段组装成菜单项title为空时回退到routeName。处理隐藏与父子关系hideChildrenInMenu为真时清空子菜单为每个子菜单设置parent/parents字段meta.hideInMenu控制show标记。排序与过滤通过sortTree按order升序排序再通过filterTree过滤掉show: false的菜单项。此外packages/utils/src/helpers/generate-routes-frontend.ts前端模式按角色过滤路由与 packages/utils/src/helpers/generate-routes-backend.ts后端模式从接口返回生成路由是两种访问模式的底层实现对应的测试见 packages/utils/src/helpers/tests/。路由刷新Vben Admin 提供了便捷的路由刷新方法使用vben/hooks中的useRefreshscript setup langts import { useRefresh } from vben/hooks; const { refresh } useRefresh(); // 刷新当前路由 refresh(); /script其底层实现位于 packages/effects/hooks/src/use-refresh.ts内部调用tabbarStore.refresh(router)完成当前标签页的重新加载因此在启用标签页功能时效果最佳。标签页与路由控制在某些场景下需要单个路由打开多个标签页或者修改路由的 query 时不打开新的标签页。每个标签页Tab使用唯一的 key 标识设置 Tab key 有三种方式优先级由高到低1. 使用路由 query 参数pageKey优先级最高script setup langts import { useRouter } from vue-router; const router useRouter(); // 跳转路由 router.push({ path: path, query: { pageKey: key, }, }); /script2. 路由的完整路径作为 key当meta中的fullPathKey不为false默认true时使用路由fullPath含 query 的完整路径作为 Tab key。3. 路由的 path 作为 key当meta中的fullPathKey为false时使用路由path作为 Tab key此时修改 query 不会新开标签页而是在当前标签内更新。利用pageKey与fullPathKey的组合可以灵活实现“详情页多开”“同页多实例”等标签页控制需求playground 中FeatureTabDetailDemo的maxNumOfOpenTab: 3即为此类场景的演示。总结Vben Admin 的路由体系由核心路由框架内置、必须存在、**静态路由启动时确定与动态路由登录后按权限生成**构成全部通过import.meta.glob自动收集并经mergeRouteModules合并。路由定义遵循“顶级绝对路径、子级相对路径”的规范多级路由的中间层级无需配置component父级redirect默认指向第一个子路由。新增页面只需在 playground/src/router/routes/modules/ 添加路由对象 在views下添加组件访问http://localhost:5555/path即可验证。路由的菜单、标签页、权限、缓存等全部行为由meta字段驱动权威类型定义见 packages/core/base/typings/src/vue-router.d.ts权限相关的路由生成与守卫流程见 playground/src/router/access.ts 与 playground/src/router/guard.ts。菜单自动生成、Tab key 控制、路由刷新等进阶能力均有对应的工具函数与 Hook 支撑可按需深入阅读 packages/utils/src/helpers/generate-menus.ts 与 packages/effects/hooks/src/use-refresh.ts。【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考