vite-plugin-auto-routes

基于约定的自动路由生成 Vite 插件，为 Vue Router 提供文件系统路由支持。

特性

• 🚀 零配置：基于文件结构自动生成路由
• 📁 约定式路由：遵循简单直观的文件命名规则
• 🔥 动态参数：支持必选和可选参数
• 🌲 嵌套路由：自动处理父子路由关系
• 🎯 私有文件：自动忽略下划线开头的文件
• ⚡ 懒加载：自动配置路由组件懒加载
• 🔌 虚拟模块：无需生成物理文件

安装

npm install vite-plugin-auto-routes-ycj
# or
pnpm add vite-plugin-auto-routes-ycj
# or
yarn add vite-plugin-auto-routes-ycj

使用

1. 配置插件

在 vite.config.js 中添加插件：

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import AutoRoutes from "vite-plugin-auto-routes-ycj";

export default defineConfig({
  plugins: [
    vue(),
    AutoRoutes({
      pagesDir: "src/views", // 可选，默认为 'src/views'
    }),
  ],
});

2. 使用生成的路由

在路由配置文件中导入虚拟模块：

import { createRouter, createWebHistory } from "vue-router";
import { routes } from "virtual:auto-routes";

const router = createRouter({
  history: createWebHistory(),
  routes,
});

export default router;

约定规则

基础路由

文件路径会自动转换为路由路径：

src/views/
├── Home.vue          → /home
├── about.vue         → /about
└── contact.vue       → /contact

index.vue 特殊处理

index.vue 文件会被映射为父级路径：

src/views/
├── index.vue         → /
└── user/
    └── index.vue     → /user

动态参数

使用 [param] 表示必选参数，使用 [[param]] 表示可选参数：

src/views/
├── user[id].vue           → /user/:id
├── post[[id]].vue         → /post/:id?
└── blog/
    └── [category]/
        └── [id].vue       → /blog/:category/:id

嵌套路由

同一目录下的 index.vue 会成为父路由，其他文件会成为子路由：

src/views/
└── user/
    ├── index.vue          → /user (父路由)
    ├── profile.vue        → /user/profile (子路由)
    └── settings.vue       → /user/settings (子路由)

组件结构示例：

<!-- user/index.vue -->
<template>
  <div>
    <h1>用户中心</h1>
    <router-view />
    <!-- 子路由出口 -->
  </div>
</template>

组合使用

支持动态参数和嵌套路由的组合：

src/views/
└── user/
    ├── index[id].vue      → /user/:id (父路由)
    ├── profile.vue        → /user/:id/profile (子路由)
    └── posts.vue          → /user/:id/posts (子路由)

私有文件

以下划线 _ 开头的文件会被忽略，不会生成路由：

src/views/
├── Home.vue               → /home
├── _component.vue         → 被忽略
└── user/
    ├── index.vue          → /user
    └── _helper.vue        → 被忽略

路由元信息

可以为每个路由创建对应的 .meta.js 或 .meta.ts 文件来添加额外的路由配置：

src/views/
├── Home.vue               → /home
├── Home.meta.js           → Home 路由的元信息
├── about.vue              → /about
└── about.meta.ts          → about 路由的元信息(支持 TypeScript)

Meta 文件示例：

// Home.meta.js
export default {
  title: "首页",
  requiresAuth: false,
  icon: "home",
  // 任何需要合并到路由对象的属性
};

// about.meta.ts
export default {
  title: "关于我们",
  requiresAuth: true,
  roles: ["admin", "user"],
};

生成的路由将包含这些信息：

{
  path: '/home',
  name: 'home',
  component: () => import('/src/views/Home.vue'),
  title: '首页',
  requiresAuth: false,
  icon: 'home'
}

配置选项

interface PluginOptions {
  /**
   * 页面目录路径
   * @default 'src/views'
   */
  pagesDir?: string;
}

生成的路由格式

插件会生成标准的 Vue Router 配置：

export const routes = [
  {
    path: "/home",
    name: "home",
    component: () => import("/src/views/Home.vue"),
    title: "首页", // 来自 Home.meta.js
    requiresAuth: false, // 来自 Home.meta.js
  },
  {
    path: "/user/:id",
    name: "userid",
    component: () => import("/src/views/user[id].vue"),
  },
  {
    path: "/user",
    name: "userindex",
    component: () => import("/src/views/user/index.vue"),
    children: [
      {
        path: "profile",
        name: "userindexprofile",
        component: () => import("/src/views/user/profile.vue"),
      },
    ],
  },
];

TypeScript 支持

如果使用 TypeScript，需要在 env.d.ts 或 vite-env.d.ts 中添加类型声明：

/// <reference types="vite/client" />

declare module "virtual:auto-routes" {
  import type { RouteRecordRaw } from "vue-router";
  export const routes: RouteRecordRaw[];
}

示例项目结构

my-app/
├── src/
│   ├── views/
│   │   ├── index.vue              → /
│   │   ├── about.vue              → /about
│   │   ├── user/
│   │   │   ├── index[id].vue     → /user/:id
│   │   │   ├── profile.vue       → /user/:id/profile
│   │   │   └── posts.vue         → /user/:id/posts
│   │   └── blog/
│   │       ├── index.vue         → /blog
│   │       └── [category]/
│   │           └── [id].vue      → /blog/:category/:id
│   ├── router/
│   │   └── index.js
│   ├── App.vue
│   └── main.js
├── vite.config.js
└── package.json

注意事项

1. 文件命名：Vue 文件必须以 .vue 结尾
2. 参数语法：
   • [id] → 必选参数 :id
   • [[id]] → 可选参数 :id?
3. 嵌套规则：只有当目录内存在 index.vue 时，同级其他文件才会成为子路由
4. 路由优先级：建议避免路径冲突，插件按文件扫描顺序生成路由
5. 热更新：修改文件结构后，Vite 会自动重新生成路由

常见问题

为什么我的路由没有生成？

• 检查文件是否在配置的 pagesDir 目录下
• 确认文件名不是以 _ 开头
• 确认文件扩展名是 .vue

如何添加路由元信息？

为路由文件创建对应的 .meta.js 或 .meta.ts 文件：

// src/views/Home.meta.js
export default {
  title: "首页",
  requiresAuth: false,
  keepAlive: true,
};

meta 文件中导出的对象会被直接合并到路由配置中，可以在路由守卫中访问：

router.beforeEach((to, from) => {
  document.title = to.title || "默认标题";
  if (to.requiresAuth && !isLoggedIn()) {
    return "/login";
  }
});

如何自定义路由配置？

生成的路由是标准的 Vue Router 配置，可以在创建路由实例后进行修改：

import { routes } from "virtual:auto-routes";

// 添加全局路由守卫、404页面等
routes.push({
  path: "/:pathMatch(.*)*",
  component: () => import("./views/NotFound.vue"),
});

const router = createRouter({
  history: createWebHistory(),
  routes,
});

许可证

MIT

作者

YCJ

贡献

欢迎提交 Issue 和 Pull Request！