告别手动配置：使用 unplugin-vue-router 自动化 Vue 3 路由

type

status

date

slug

summary

category

icon

password

引言:

在 Vue 3 项目开发中，路由管理是构建单页应用（SPA）的核心环节。传统的路由配置方式，尤其是在页面数量庞大的大型项目中，往往涉及大量手动编写和维护路由规则的代码，这不仅耗时，也容易出错。

为了解决这一痛点，今天我们介绍一款强大的 Vite/Webpack 插件——unplugin-vue-router。它遵循“约定优于配置”的原则，能够根据您的 Vue 组件文件结构自动生成类型安全的路由配置，显著提升开发效率和代码可维护性。

unplugin-vue-router 简介

unplugin-vue-router 是一个构建时（Build-time）插件，它扫描您项目中特定目录（默认为 src/pages）下的 Vue 组件，并基于文件路径和命名约定自动生成对应的 vue-router 配置。

这意味着您不再需要手动维护一个庞大的 routes 数组。只需按照约定创建和组织您的页面组件，路由即可自动生效，并获得 TypeScript 的类型支持。

核心优势:

自动化: 无需手动编写路由配置，减少样板代码。

约定驱动: 基于文件系统结构，直观易懂。

类型安全: 自动生成类型定义，提供路由名称、参数的自动补全和编译时检查。

集成性: 基于 unplugin，同时支持 Vite、Webpack、Rollup 等主流构建工具。

安装与配置

第一步：安装插件

在您的 Vue 3 项目根目录下执行安装命令：

第二步：配置构建工具 (以 Vite 为例)

编辑您的 vite.config.ts (或 .js) 文件，引入并配置插件：

重要提示: VueRouter() 插件必须在 vue() 插件之前注册，因为它需要先处理路由生成，再由 vue() 插件处理 Vue 组件。

第三步：配置 Vue Router 实例

修改您的路由入口文件（通常是 src/router/index.ts），使用插件提供的自动生成的路由：

注意: 这里我们从 vue-router/auto 导入 createRouter 和 createWebHistory。这是插件创建的一个“代理”模块，它会包含自动生成的路由，并提供类型增强。同时，从 vue-router/auto-routes 导入 routes 变量。

基于文件的路由规则 (约定)

unplugin-vue-router 会根据 src/pages (或您配置的 routesFolder) 目录下的文件结构自动创建路由：

src/pages/index.vue -> /

src/pages/about.vue -> /about

src/pages/users/index.vue -> /users

src/pages/users/profile.vue -> /users/profile

动态路由: src/pages/users/[id].vue -> /users/:id (id 作为参数)

嵌套路由: 在 src/pages 下创建一个与父组件同名的目录，并在该目录下创建子路由组件。例如:

src/pages/settings.vue (父路由组件，需要包含 <RouterView />)
src/pages/settings/profile.vue -> /settings/profile (作为 /settings 的子路由)
src/pages/settings/index.vue -> /settings (作为 /settings 的默认子路由)

捕获所有路由 (404): src/pages/[...all].vue -> /:all(.*) (通常用于 404 页面)

更详细的路由规则和命名约定（如命名路由、路由元信息等），请查阅 unplugin-vue-router 官方文档。

自定义与扩展路由

虽然自动化是核心，但您仍然可以方便地添加或修改路由配置。在 src/router/index.ts 中扩展 routes 数组即可：

实现原理简析 (可选深入了解)

unplugin-vue-router 利用了 unplugin 提供的跨构建工具能力，其核心工作流程如下：

配置读取与扫描: 插件启动时读取 vite.config.ts 或其他构建工具配置中的选项（如 routesFolder）。

文件系统监听: 在开发模式下，监听 routesFolder 内的文件变化（增、删、改、重命名）。

路由树构建: 根据文件路径和命名约定，在内存中构建路由配置树。

虚拟模块生成:

vue-router/auto-routes: 生成包含实际 routes 数组代码的虚拟模块。

vue-router/auto: 生成一个代理模块，它重新导出了 vue-router 的所有 API，但对其进行了类型增强，并可能注入了生成的路由信息。

构建工具通过 resolveId 和 load 钩子拦截对这些虚拟模块的导入请求，并返回插件动态生成的代码。 (此处可插入原图1和图2，并配文字说明：图1 - resolveId 钩子拦截虚拟模块；图2 - load 钩子返回生成的路由代码)

类型声明生成: 根据构建的路由树，生成 TypeScript 声明文件 (.d.ts)。这使得在使用 useRouter, <RouterLink> 等 API 时，可以获得路由名称、参数的类型提示和检查。 (此处可插入原图3，说明生成的代理模块)(此处可插入原图4，解释 .d.ts 文件如何提供 VSCode 提示)