自动生成前端路由最佳实践本文档介绍如何使用 vite 和 vite-plugin-pages 在前端项目中自动生成前端路

自动生成前端路由最佳实践

概述

本文档介绍如何使用 vite 和 vite-plugin-pages 在前端项目中自动生成前端路由，通过文件系统结构自动映射为路由配置，减少手动维护路由的工作量。

安装必要依赖

首先需要安装用于自动生成路由的插件：

npm install vite-plugin-pages --save-dev
# 或
yarn add vite-plugin-pages -D
# 或
pnpm add vite-plugin-pages -D

配置 Vite

在 vite.config.ts 中配置插件：

import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import Pages from 'vite-plugin-pages'

export default defineConfig({
  plugins: [
    Vue(),
    Pages({
      // 基本配置选项
      dirs: 'src/views', // 路由组件目录
      exclude: ['**/components/*.vue'], // 排除的组件
      extensions: ['vue'], // 支持的文件类型
      // 更多配置见下文
    }),
  ],
})

基本使用

文件系统路由约定

默认情况下，插件会扫描 src/views 目录下的 .vue 文件并自动生成路由：

src/views/
  ├── index.vue        -> /
  ├── about.vue        -> /about
  ├── users/
  │   ├── index.vue    -> /users
  │   └── [id].vue     -> /users/:id
  └── blog/
      ├── index.vue    -> /blog
      └── [slug].vue   -> /blog/:slug

动态路由

使用方括号命名文件来创建动态路由：

[param].vue -> /:param
[...all].vue -> /*

嵌套路由（不推荐）

创建与父路由同名的目录来生成嵌套路由：

src/views/
  ├── users/
  │   ├── [id].vue
  │   └── index.vue
  └── users.vue

会生成如下路由结构：

{
  "path": "/users",
  "component": "/src/views/users.vue",
  "children": [
    {
      "path": "",
      "component": "/src/views/users/index.vue"
    },
    {
      "path": ":id",
      "component": "/src/views/users/[id].vue"
    }
  ]
}

高级配置(自定义路由属性)

可以在页面组件中使用 <route> 块来自定义路由属性：

<route>
{
  "meta": {
    "requiresAuth": true
  },
  "alias": ["/home"]
}
</route>

<template>
  <div>Home Page</div>
</template>

修改默认路由

在插件配置中可以通过 extendRoute 修改生成的路由：

Pages({
  extendRoute(route, parent) {
    if (route.path === '/') {
      return {
        ...route,
        alias: ['/home']
      }
    }
    return route
  }
})

使用不同的路由模式

支持生成 vue-router 或 react-router 格式的路由：

Pages({
  routerMode: 'vue' // 或 'react'
})

与路由库集成

Vue Router 集成

import { createRouter } from 'vue-router'
import routes from 'virtual:generated-pages'

const router = createRouter({
  // ...
  routes,
})

React Router 集成

import { createBrowserRouter } from 'react-router-dom'
import routes from 'virtual:generated-pages'

const router = createBrowserRouter(routes)

类型支持

对于 TypeScript 项目，添加以下类型声明：

/// <reference types="vite-plugin-pages/client" />

完整配置选项

选项	类型	默认值	描述
`dirs`	string \| array	'src/pages'	要扫描的目录
`extensions`	string[]	['vue', 'md']	支持的文件扩展名
`exclude`	string[]	[]	要排除的 glob 模式
`importMode`	'sync' \| 'async' \| function	'async'	导入组件的方式
`routeBlockLang`	string	'json5'	`<route>` 块的语言
`routerMode`	'vue' \| 'react'	'vue'	生成的路由格式
`nuxtStyle`	boolean	false	是否使用 Nuxt.js 风格的路由
`replaceSquareBrackets`	boolean	false	是否替换动态路由的方括号
`extendRoute`	function	undefined	扩展/修改生成的路由

示例项目结构

my-project/
├── src/
│   ├── pages/
│   │   ├── index.vue
│   │   ├── about.vue
│   │   ├── users/
│   │   │   ├── [id].vue
│   │   │   └── index.vue
│   │   └── blog/
│   │       ├── index.vue
│   │       └── [slug].vue
│   ├── App.vue
│   └── main.ts
├── vite.config.ts
└── package.json

注意事项

生产构建时会预生成路由配置，不会影响性能
热更新在开发模式下正常工作
可以通过 console.log(routes) 查看生成的路由结构
对于需要特殊处理的路由，仍然可以手动维护部分路由配置