vue-auto-router

基于文件系统的 Vue Router 自动路由：扫描 views/ 目录并生成嵌套路由树。

推荐用法

vue-auto-router 的运行时不直接扫描文件。由于 Vite 的 import.meta.glob 必须使用字面量字符串，调用方需要在应用侧收集页面模块；页面 defineMeta 推荐交给 vue-auto-router/vite 插件在构建期提取，避免浏览器运行时携带 raw 源码。

// vite.config.ts
import { fileURLToPath, URL } from "node:url";
import vue from "@vitejs/plugin-vue";
import { defineConfig } from "vite";
import { vueAutoRouterMetaPlugin } from "vue-auto-router/vite";

const srcRoot = fileURLToPath(new URL("./src", import.meta.url));

export default defineConfig({
  plugins: [
    vueAutoRouterMetaPlugin({
      aliasRootAt: srcRoot,
    }),
    vue(),
  ],
  resolve: {
    alias: {
      "@": srcRoot,
    },
  },
});

import { createAutoRouter } from "vue-auto-router";
import pageMetaMap from "vue-auto-router/meta";
import Layout from "@/Layout/index.vue";
import Blank from "@/Layout/blank/Blank.vue";

const { router, manager } = createAutoRouter({
  modules: import.meta.glob("@/views/**/*.vue"),
  pageMetaMap,
  directoryMetaModules: import.meta.glob("@/views/**/routeMeta.ts", {
    query: "?raw",
    import: "default",
    eager: true,
  }),
  layout: Layout,
  blankLayout: Blank,
  defaultRedirect: "/home",
  debug: import.meta.env.DEV,
});

export { manager };
export default router;

如果不使用 Vite 插件，也可以传入 rawModules，由 ModuleParser 从页面源码中解析 defineMeta：

createAutoRouter({
  modules: import.meta.glob("@/views/**/*.vue"),
  rawModules: import.meta.glob("@/views/**/*.vue", {
    query: "?raw",
    import: "default",
    eager: true,
  }),
  directoryMetaModules: import.meta.glob("@/views/**/routeMeta.ts", {
    query: "?raw",
    import: "default",
    eager: true,
  }),
  layout: Layout,
  blankLayout: Blank,
});

约定

• 仅解析 views/**/index.vue 文件
• 路径如 views/system/user/index.vue → 路由 /system/user
• 多级嵌套时父级使用 blankLayout 组件 + 重定向到首个子路由
• 页面内通过 defineMeta({...}) 声明路由元信息（title/hidden/keepAlive/icon/order/public/roles/layout）
• 无实际页面的目录节点可通过 views/**/routeMeta.ts 声明目录元信息
• meta.layout === false 的顶层路由会独立挂载，不进入根 Layout，适合登录页、错误页等场景
• 根路径 / 默认重定向到第一个 meta.home === true 的 Layout 子路由；没有配置时回落到第一个 Layout 子路由

defineMeta 宏

通过 unplugin-auto-import 配置后即可在页面中直接使用：

// vite.config.ts
import AutoImport from "unplugin-auto-import/vite";

AutoImport({
  imports: [{ "vue-auto-router/macro": ["defineMeta"] }],
});

<script setup lang="ts">
defineMeta({
  title: "用户管理",
  keepAlive: true,
  order: 2,
});
</script>

目录元信息（无 index.vue）

import type { ViewRouteMeta } from "vue-auto-router";

export default {
  title: "系统管理",
  order: 10,
  icon: "setting",
} satisfies ViewRouteMeta;

模块职责

• ModuleParser：解析 import.meta.glob 传入的页面模块、页面 meta 和目录 meta，产出统一的 ModuleInfo[]
• RouteTreeBuilder：把 ModuleInfo[] 组装成 Vue Router 嵌套路由树，中间层目录使用 blankLayout
• createAutoRouter：拆分 Layout 子路由和独立路由，创建并注册 Vue Router 实例
• RouteManager：面向布局层提供菜单、keepAlive、首页路径、active menu 等查询能力
• vueAutoRouterMetaPlugin：构建期扫描 views/**/index.vue，生成 vue-auto-router/meta 虚拟模块

API

createAutoRouter(options)

| 字段 | 类型 | 说明 | | ------------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------- | | modules | Record<string, () => Promise<{ default: unknown }>> | 页面懒加载映射 | | rawModules | Record<string, string> | 页面源码映射（未使用 Vite 插件时用于提取 defineMeta） | | pageMetaMap | Record<string, ViewRouteMeta \| undefined> | Vite 插件生成的页面 meta 映射，优先级高于 rawModules | | directoryMetaModules | Record<string, string> | routeMeta.ts 源码映射 | | layout | Component | 根布局 | | blankLayout | Component | 嵌套容器布局 | | history | RouterHistory | 默认 createWebHistory() | | defaultRedirect | string | / 的默认重定向，默认优先使用 meta.home，再回落到首个 Layout 子路由 | | debug | boolean | 是否打印调试日志 | | layoutName | string | 根布局路由 name，默认 'Layout' | | viewPathRegex | RegExp | 自定义视图路径匹配 | | directoryMetaPathRegex | RegExp | 自定义目录元信息匹配 |

返回 { router, manager }：

• router — Vue Router 实例
• manager — RouteManager 实例，提供菜单过滤、keepAlive 名单、嵌套路由查询等能力

RouteManager

• getNestedRoutes() — 原始嵌套路由
• getFlatRoutes() — Vue Router 打平后的路由
• getMenuItems(roles?) — 过滤 meta.hidden / 角色后的菜单树（MenuItem[]，绝对路径 + 已解析的 title / icon，按 meta.order 排序）
• getKeepAliveRoutes(roles?) — 需要 keep-alive 的 name 列表
• getHomePath() — 返回与根布局 redirect 一致的首页路径
• resolveActiveMenuPath(currentPath, roles?) — 根据当前路由和 meta.activeMenu 推导菜单高亮路径
• getMenuOpenPaths(activePath, roles?) — 返回当前菜单应展开的父级路径链
• findNestedRoute(path) — 按完整路径查找
• getFullPath(route, parent?) — 计算完整路径

环境要求

• Node.js：见 package.json 的 engines.node（与仓库要求一致，当前为 ≥ 22.21.1）。
• vue-auto-router/vite 依赖 Vite ≥ 5（peerDependencies）；vue / vue-router 由本包直接依赖，请与宿主工程保持主版本一致以避免多实例。

License

ISC