告别繁琐的路由配置：vite-plugin-convention-routes 让你的 Vue 项目更优雅

告别繁琐的路由配置：vite-plugin-convention-routes 让你的 Vue 项目更优雅

前言

在开发 Vue 应用时，路由配置往往是一项繁琐且容易出错的工作。随着项目规模的增长，路由文件会变得越来越臃肿，维护成本也随之增加。每当我们新增一个页面，都需要手动更新路由配置，这不仅降低了开发效率，还容易引入错误。

vite-plugin-convention-routes。这是一款类似 Umi 的约定式路由插件，可以自动根据文件结构生成路由配置，减少 80% 的路由样板代码，降低 90% 的路由 BUG。

约定式路由的优势

传统的路由配置方式需要我们手动维护路由表，而约定式路由则是通过文件系统的结构自动生成路由配置。这种方式有以下几个显著优势：

1. 简化开发流程：无需手动编写和维护路由配置，只需关注页面组件开发
2. 降低维护成本：路由结构与文件结构一致，一目了然，易于理解和维护
3. 减少错误：自动生成的路由配置不会出现手误导致的路径错误、组件引用错误等问题
4. 提高开发效率：新增页面只需创建文件，无需修改路由配置
5. 更好的团队协作：统一的路由约定减少了团队成员之间的沟通成本

vite-plugin-convention-routes 的核心特性

1. 约定式路由

根据文件目录结构自动生成路由配置，无需手动维护路由表。例如：

• src/views/index.vue → 路由: /
• src/views/about.vue → 路由: /about
• src/views/users/index.vue → 路由: /users

2. 动态路由参数

支持使用 [param] 语法定义动态路由参数，并支持多级嵌套：

• src/views/users/[id].vue → 路由: /users/:id
• src/views/posts/[id]/comments/[commentId].vue → 路由: /posts/:id/comments/:commentId

3. 布局组件

使用 _layout.vue 文件作为特定目录的布局组件，实现嵌套路由和共享布局：

src/views/users/
├── _layout.vue     # 布局组件，所有 /users 路径下的页面都将嵌套在这个布局中
├── index.vue       # /users 路径的页面
└── [id].vue        # /users/:id 路径的页面

4. 路由元数据

支持通过配置文件或组件内定义路由元数据，便于实现权限控制、面包屑导航等功能：

<script>
// 在组件内定义路由元数据
export const routeMeta = {
  title: '用户管理',
  icon: 'user-group',
  permissions: ['admin']
}
</script>

5. 懒加载

默认支持路由组件懒加载，提升应用性能：

// 自动生成类似这样的懒加载代码
const routes = [
  {
    path: '/users',
    component: () => import('/src/views/users/index.vue')
  }
]

6. 类型安全

自动生成 TypeScript 类型声明文件，提供完整的类型支持。

7. 热更新

支持路由文件的热更新，修改路由文件后无需重启开发服务器。

安装与使用

1. 安装插件

# 使用 npm
npm install vite-plugin-convention-routes --save-dev

# 使用 yarn
yarn add vite-plugin-convention-routes --dev

# 使用 pnpm
pnpm add vite-plugin-convention-routes -D

2. 配置 Vite 插件

在 vite.config.js 或 vite.config.ts 中添加插件配置：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import conventionRoutes from 'vite-plugin-convention-routes'

export default defineConfig({
  plugins: [
    vue(),
    conventionRoutes({
      // 路由文件所在目录
      routesDir: 'src/views',
      // 是否生成类型声明文件
      generateDeclaration: true,
      // 是否在控制台打印路由信息
      verbose: true,
      // 是否开启路由懒加载
      isLazy: true,
      // 需要排除的目录
      excludes: ['components', 'common'],
      // 布局文件名
      layoutName: '_layout'
    })
  ]
})

3. 创建路由文件

// src/router/index.js 或 src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router'

// 这里的 routes 数组会被插件自动替换为约定式路由
const routes = []

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

export default router

4. 按约定组织文件结构

src/views/
├── index.vue                   # 路由: /
├── about.vue                   # 路由: /about
├── users/
│   ├── _layout.vue             # 布局组件: /users 的布局
│   ├── index.vue               # 路由: /users
│   └── [id].vue                # 路由: /users/:id
└── posts/
    ├── index.vue               # 路由: /posts
    └── [id].vue                # 路由: /posts/:id

深入理解约定式路由

路由映射规则

1. 基本规则：

   • 文件路径直接映射到 URL 路径
   • index.vue 文件映射到父路径
   • 其他文件名直接映射到路由路径

2. 动态参数：

   • [param].vue 文件映射到动态路由参数 :param
   • 支持多级嵌套，如 users/[id]/posts/[postId].vue → /users/:id/posts/:postId

3. 布局组件：

   • _layout.vue 文件作为父路由的布局组件
   • 同一目录下的其他文件将作为子路由嵌套在布局组件中

布局组件示例

布局组件是一种特殊的组件，用于为特定目录下的所有路由提供共享布局：

<!-- src/views/users/_layout.vue -->
<template>
  <div class="users-layout">
    <h1>用户模块</h1>
    <nav>
      <router-link to="/users">用户列表</router-link>
      <router-link to="/users/create">创建用户</router-link>
    </nav>
    
    <!-- 子路由内容将在这里渲染 -->
    <router-view></router-view>
  </div>
</template>

这样，所有 /users 路径下的页面都会共享这个布局，无需在每个页面中重复实现相同的结构。

路由元数据配置

路由元数据对于实现权限控制、导航菜单、面包屑等功能非常有用。vite-plugin-convention-routes 提供了两种定义元数据的方式：

1. 通过配置文件定义

// src/router/route-meta.js
export default {
  '/': {
    title: '首页',
    icon: 'home',
    keepAlive: true
  },
  '/users': {
    title: '用户管理',
    permissions: ['admin'],
    icon: 'user-group'
  }
}

2. 在组件内定义

<template>
  <div>用户列表页面</div>
</template>

<script>
/* route-meta
{
  "title": "用户管理",
  "icon": "user-group",
  "permissions": ["admin"],
  "keepAlive": true
}
*/
export default {
  name: 'UserList'
}
</script>

或者通过导出变量：

<script>
// 使用导出变量的方式定义路由元数据
export const routeMeta = {
  title: '用户管理',
  icon: 'user-group',
  permissions: ['admin']
}

export default {
  name: 'UserList'
}
</script>

实际案例：从传统路由迁移到约定式路由

传统路由配置

// 传统的路由配置
const routes = [
  {
    path: '/',
    component: () => import('./views/Home.vue')
  },
  {
    path: '/about',
    component: () => import('./views/About.vue')
  },
  {
    path: '/users',
    component: () => import('./views/users/Layout.vue'),
    children: [
      {
        path: '',
        component: () => import('./views/users/List.vue')
      },
      {
        path: ':id',
        component: () => import('./views/users/Detail.vue')
      }
    ]
  },
  {
    path: '/posts',
    component: () => import('./views/posts/List.vue')
  },
  {
    path: '/posts/:id',
    component: () => import('./views/posts/Detail.vue')
  }
]

约定式路由结构

使用 vite-plugin-convention-routes 后，只需按照约定组织文件结构：

src/views/
├── index.vue                # 对应 /
├── about.vue                # 对应 /about
├── users/
│   ├── _layout.vue          # 对应 /users 的布局
│   ├── index.vue            # 对应 /users
│   └── [id].vue             # 对应 /users/:id
└── posts/
    ├── index.vue            # 对应 /posts
    └── [id].vue             # 对应 /posts/:id

然后在路由文件中只需简单配置：

// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router'

const routes = [] // 这里会被自动替换为约定式路由

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

export default router

插件会自动生成与传统配置等效的路由配置，但维护成本大大降低。

高级用法

1. 多级动态参数

支持多级嵌套的动态参数，适用于复杂的应用场景：

src/views/courses/[courseId]/chapters/[chapterId]/lessons/[lessonId].vue

这将生成路由 /courses/:courseId/chapters/:chapterId/lessons/:lessonId。

2. 结合权限控制

结合路由元数据实现权限控制：

// 路由守卫
router.beforeEach((to, from, next) => {
  const { meta } = to
  const { permissions } = meta
  
  if (permissions && !hasPermission(permissions)) {
    next('/403')
  } else {
    next()
  }
})

3. 自定义配置

插件提供了丰富的配置选项，可以根据项目需求进行定制：

选项	类型	默认值	描述
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	是否启用组件内定义元数据

性能优化

vite-plugin-convention-routes 不仅简化了路由配置，还通过以下方式优化应用性能：

1. 路由懒加载：默认启用懒加载，按需加载路由组件
2. 热更新优化：修改路由文件时只更新相关模块，无需重启服务器
3. 构建优化：生成优化的路由配置，减少运行时开销

与其他框架/插件的比较

特性	vite-plugin-convention-routes	vue-router	vite-plugin-pages	umi
约定式路由	✅	❌	✅	✅
动态路由参数	✅	✅	✅	✅
多级嵌套参数	✅	✅	⚠️ (有限支持)	✅
布局组件	✅	❌	⚠️ (需额外配置)	✅
路由元数据	✅	✅	✅	✅
组件内元数据	✅	❌	✅	⚠️
TypeScript支持	✅	✅	✅	✅
热更新	✅	⚠️	✅	✅
配置灵活性	✅	✅	⚠️	⚠️

实际项目中的应用

vite-plugin-convention-routes 适用于各种规模的 Vue 项目，尤其是：

1. 中大型应用：路由配置复杂，手动维护成本高
2. 多人协作项目：统一的路由约定减少沟通成本
3. 需要频繁迭代的项目：快速添加/修改路由，提高开发效率
4. 需要严格权限控制的系统：利用路由元数据实现精细的权限管理

常见问题解答

Q1: 这个插件只能用于 Vue 项目吗？

A: 目前主要支持 Vue 项目，但原理上也可以用于其他框架，只需调整相关配置。

Q2: 如何处理 404 页面？

A: 可以在路由配置中添加通配符路由：

// 在 router/index.js 中添加
router.addRoute({
  path: '/:pathMatch(.*)*',
  component: () => import('./views/NotFound.vue')
})

Q3: 如何与 TypeScript 结合使用？

A: 插件默认生成 TypeScript 类型声明文件，确保在 tsconfig.json 中包含生成的声明文件路径即可。

总结

vite-plugin-convention-routes 通过约定式路由的方式，极大地简化了 Vue 项目中的路由配置工作。它不仅提高了开发效率，还降低了维护成本和出错率。无论是新项目还是现有项目，都可以轻松集成这个插件，享受约定式路由带来的便利。

如果你厌倦了手动维护繁琐的路由配置，不妨尝试 vite-plugin-convention-routes，让你的 Vue 项目开发更加高效和优雅。

参考资源

• GitHub 仓库
• NPM 包
• 示例项目
• Vue Router 官方文档
• Vite 官方文档