vite-plugin-pages 是基于文件系统自动生成路由的 Vite 插件，通过扫描指定目录下的 .vue 文件，自动映射为路由配置，消除手动维护路由表的重复工作。本文讲解其目录映射规则、重定向配置和路由扩展机制。
pnpm add -D vite-plugin-pages// vite.config.ts
import Pages from 'vite-plugin-pages'
export default defineConfig({
plugins: [
vue(),
Pages({
dirs: ['src/pages'],
extensions: ['vue'],
exclude: ['**/components/**'],
})
]
})src/pages/
├── index.vue → { path: '/' }
├── about.vue → { path: '/about' }
├── user/
│ ├── index.vue → { path: '/user' }
│ ├── profile.vue → { path: '/user/profile' }
│ └── [id].vue → { path: '/user/:id' }
└── [...path].vue → { path: '/:pathMatch(.*)*' } (404)映射规则：
| 文件命名 | 路由路径 | 说明 |
|---|---|---|
index.vue | / 或父路径 | 目录默认页 |
about.vue | /about | 普通页面 |
[id].vue | /:id | 动态参数 |
[...path].vue | /:path(.*)* | 通配符（404） |
| 方案 | 配置位置 | 特点 |
|---|---|---|
| 编程式导航 | 组件内 onMounted | 通用、速度快 |
<route> SFC 块 | 组件内自定义块 | 逻辑清晰 |
<route> JSON | 组件内 JSON 块 | 纯声明式 |
| 入口文件逻辑 | main.ts | 全局统一处理 |
| extendRoute | vite.config.ts | 配置文件级扩展 |
<!-- src/pages/home.vue -->
<script setup lang="ts">
import { onMounted } from 'vue'
import { useRouter } from 'vue-router'
const router = useRouter()
onMounted(() => router.push('/'))
</script><route> 自定义块<!-- src/pages/home.vue -->
<route lang="yaml">
redirect: '/'
</route>
<template>
<div>正在跳转...</div>
</template>// vite.config.ts
Pages({
extendRoute(route) {
if (route.path === '/home') {
return { ...route, redirect: '/' }
}
return route
}
})<route> 块设置 meta<route lang="yaml">
meta:
requiresAuth: true
title: 用户中心
</route>Pages({
extendRoute(route) {
return {
...route,
meta: {
...route.meta,
title: route.name,
}
}
}
})// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
import routes from '~pages' // 插件提供的虚拟模块
const router = createRouter({
history: createWebHistory(),
routes,
})
export default router~pages 是插件注册的虚拟模块，编译时替换为自动生成的路由数组。
Q: 如何排除某些文件不生成路由？
使用 exclude 配置项，支持 glob 模式：exclude: ['**/components/**', '**/_*.vue']。以下划线开头的文件通常作为布局组件而非页面。
Q: 嵌套路由如何生成？
目录嵌套自动映射为嵌套路由。user/profile.vue 生成 /user/profile；如需父布局路由，应在与 user/ 目录同级放置同名 user.vue 作为父路由组件包裹子路由（vite-plugin-pages 没有 _layout.vue 布局约定，_ 前缀仅在 routeStyle: 'nuxt' 下表示动态参数）。