Vite 约定式路由插件

一个类似Umi的约定式路由Vite插件，可以自动根据文件结构生成路由配置，减少80%路由样板代码，降低90%的路由BUG。

特性

• 📁 约定式路由 - 根据文件目录结构自动生成路由配置
• 🔄 动态路由 - 支持 [param] 语法的动态路由参数，支持多个参数嵌套
• 🚀 懒加载 - 默认支持路由组件懒加载，提升应用性能
• 🔍 类型安全 - 自动生成TypeScript类型声明
• 🔌 易于集成 - 与Vue Router无缝集成
• 🔥 热更新 - 支持路由文件的热更新
• 🧩 排除目录 - 支持排除特定目录，如组件库目录不生成路由
• 📋 布局组件 - 支持 _layout.vue 作为父路由的布局组件，实现嵌套路由
• 📋 路由元数据 - 支持路由元数据配置（通过配置文件或组件内定义）

安装

1# 使用npm
2npm install vite-plugin-convention-routes --save-dev
3
4# 使用yarn
5yarn add vite-plugin-convention-routes --dev
6
7# 使用pnpm
8pnpm add vite-plugin-convention-routes -D

使用方法

配置Vite插件

1// vite.config.js / vite.config.ts
2import { defineConfig } from 'vite'
3import vue from '@vitejs/plugin-vue'
4import conventionRoutes from 'vite-plugin-convention-routes'
5
6export default defineConfig({
7  plugins: [
8    vue(),
9    conventionRoutes({
10      // 路由文件所在目录
11      routesDir: 'src/views',
12      // 是否生成类型声明文件
13      generateDeclaration: true,
14      // 是否在控制台打印路由信息
15      verbose: true,
16      // 是否开启路由懒加载
17      isLazy: true,
18      // 需要排除的目录
19      excludes: ['components', 'common'],
20      // 布局文件名
21      layoutName: '_layout'
22    })
23  ]
24})

创建路由文件

1// src/router/index.js 或 src/router/index.ts
2import { createRouter, createWebHistory } from 'vue-router'
3
4// 这里的routes数组会被插件自动替换为约定式路由
5const routes = []
6
7export const router = createRouter({
8  history: createWebHistory(),
9  routes
10})
11
12export default router

文件结构约定

src/views/
├── index.vue                   # 路由: /
├── about.vue                   # 路由: /about
├── users/
│   ├── _layout.vue             # 布局组件: /users 的布局
│   ├── index.vue               # 路由: /users
│   ├── [id].vue                # 路由: /users/:id
│   └── [id]/
│       ├── index.vue           # 路由: /users/:id
│       ├── profile.vue         # 路由: /users/:id/profile
│       └── settings.vue        # 路由: /users/:id/settings
├── exam/
│   ├── _layout.vue             # 布局组件: /exam 的布局
│   ├── index.vue               # 路由: /exam
│   └── [courseId]/
│       ├── index.vue           # 路由: /exam/:courseId
│       └── [chapterId]/
│           └── index.vue       # 路由: /exam/:courseId/:chapterId
├── posts/
│   ├── index.vue               # 路由: /posts
│   └── [id].vue                # 路由: /posts/:id
└── components/                 # 默认被排除，不生成路由
    ├── Header.vue              # 不会生成路由
    └── Footer.vue              # 不会生成路由

生成的路由配置示例

以上文件结构将生成如下路由配置：

1[
2  {
3    "path": "/",
4    "component": "() => Component",
5    "name": "home"
6  },
7  {
8    "path": "/about",
9    "component": "() => Component",
10    "name": "about",
11    "originalFilePath": "/src/views/about.vue"
12  },
13  {
14    "path": "/exam",
15    "component": "() => Component",
16    "children": [
17      {
18        "path": ":courseId/:chapterId",
19        "component": "() => Component",
20        "name": "exam-courseId-chapterId",
21        "originalFilePath": "/src/views/exam/[courseId]/[chapterId]/index.vue"
22      },
23      {
24        "path": ":courseId",
25        "component": "() => Component",
26        "name": "exam-courseId",
27        "originalFilePath": "/src/views/exam/[courseId]/index.vue"
28      },
29      {
30        "path": "",
31        "component": "() => Component",
32        "name": "exam",
33        "originalFilePath": "/src/views/exam/index.vue"
34      }
35    ]
36  },
37  {
38    "path": "/users",
39    "component": "() => Component",
40    "children": [
41      {
42        "path": ":id",
43        "component": "() => Component",
44        "name": "users-id",
45        "originalFilePath": "/src/views/users/[id].vue"
46      },
47      {
48        "path": "",
49        "component": "() => Component",
50        "name": "users",
51        "originalFilePath": "/src/views/users/index.vue"
52      }
53    ]
54  }
55]

注意：实际生成的路由配置中，"() => Component" 是真实的组件引用函数，这里只是为了展示而简化。

布局组件

布局组件是一种特殊的组件，用于为特定目录下的所有路由提供共享布局。布局组件命名为 _layout.vue，放置在需要应用布局的目录中。

例如，src/views/users/_layout.vue 将作为 /users 路径下所有路由的布局组件，所有 /users/ 开头的路由都将嵌套在这个布局组件内。布局组件需要包含 <router-view></router-view> 标签来显示子路由内容。

1<!-- src/views/users/_layout.vue -->
2<template>
3  <div class="users-layout">
4    <h1>用户模块</h1>
5    <nav>
6      <router-link to="/users">用户列表</router-link>
7      <!-- 其他导航链接 -->
8    </nav>
9    
10    <!-- 子路由内容将在这里渲染 -->
11    <router-view></router-view>
12  </div>
13</template>

路由规则

• index.vue 文件映射到父路径
• [param].vue 文件映射到动态路由参数 :param
• 支持多个动态参数嵌套，如 /exam/[courseId]/[chapterId] 映射为 /exam/:courseId/:chapterId
• 其他文件名直接映射到路由路径

配置选项

选项	类型	默认值	描述
routesDir	string	'src/views'	路由文件所在目录
extensions	string[]	['.vue']	要处理的文件扩展名
generateDeclaration	boolean	true	是否生成路由声明文件
declarationPath	string	'src/router/routes.d.ts'	路由声明文件输出路径
verbose	boolean	false	是否在控制台打印路由信息
isLazy	boolean	true	是否开启路由懒加载
excludes	string[]	['components']	需要排除的目录，这些目录下的文件不会被添加到路由配置中
layoutName	string	'_layout'	布局文件名，用于识别布局组件
metaConfigPath	string	'src/router/route-meta.js'	路由元数据配置文件路径
enableInComponentMeta	boolean	true	是否启用组件内定义元数据

路由元数据配置

1. 通过配置文件定义元数据

可以创建专门的配置文件来定义路由元数据：

1// src/router/route-meta.js
2export default {
3  '/': {
4    title: '首页',
5    icon: 'home',
6    keepAlive: true
7  },
8  '/users': {
9    title: '用户管理',
10    permissions: ['admin'],
11    icon: 'user-group'
12  },
13  '/users/:id': {
14    title: '用户详情',
15    parentPath: '/users',
16    breadcrumb: true
17  }
18}

2. 在组件内定义元数据

可以使用两种方式在组件内定义元数据：

方式一：注释块

使用特定格式的注释块来定义元数据：

1<template>
2  <div>用户列表页面</div>
3</template>
4
5<script>
6/* route-meta
7{
8  "title": "用户管理",
9  "icon": "user-group",
10  "permissions": ["admin"],
11  "keepAlive": true
12}
13*/
14export default {
15  name: 'UserList'
16}
17</script>

方式二：导出变量

通过导出 routeMeta 变量来定义元数据：

1<template>
2  <div>关于页面</div>
3</template>
4
5<script>
6// 使用导出变量的方式定义路由元数据
7export const routeMeta = {
8  title: '关于我们',
9  icon: 'info-circle',
10  isPublic: true,
11  noCache: true
12}
13
14export default {
15  name: 'AboutPage'
16}
17</script>

元数据优先级

如果同一个路由在多个地方定义了元数据，优先级如下：

1. 组件内定义的元数据（最高优先级）
2. 配置文件中定义的元数据
3. 默认元数据（如果有）

开发

1# 安装依赖
2pnpm install
3
4# 开发模式
5pnpm run dev
6
7# 构建插件
8pnpm run build
9
10# 运行测试
11pnpm test

示例

查看 example 目录中的示例项目，了解如何使用此插件。示例中包含了多级路由参数的实际应用，如 /exam/:courseId/:chapterId。

许可证

MIT