基础介绍

约 1414 字大约 5 分钟

2025-09-19

Unplugin Vue Router 能帮你自动生成路由，让你从繁琐的手动配置中解脱出来，提升开发效率。下面是一份基础使用说明，助你快速上手。

下面是一个表格，帮你快速了解 Unplugin Vue Router 如何根据文件结构生成路由：

文件路径	访问路径 (Route)	说明
`src/pages/index.vue`	`/`	首页
`src/pages/about.vue`	`/about`	关于页面
`src/pages/users/index.vue`	`/users`	用户列表页
`src/pages/users/[id].vue`	`/users/:id`	用户详情页，`[id]` 为必需参数
`src/pages/users/[[id]].vue`	`/users/:id?`	用户页，`[[id]]` 为可选参数
`src/pages/articles/[slugs]+.vue`	`/articles/:slugs+`	文章页，`[slugs]+` 可匹配一个或多个路径段
`src/pages/[...404].vue`	`/*`	404 页面，捕获所有未定义的路由
`src/pages/parent.vue`	`/parent`	父路由组件，需包含 `<router-view>` 用于渲染子路由
`src/pages/parent/child.vue`	`/parent/child`	子路由组件，路径会自动嵌套

🔧 安装与配置

1. 安装插件

在你的 Vue 3 项目中，通过 npm 或 yarn 等包管理器安装 unplugin-vue-router。

npm install -D unplugin-vue-router
# 或
yarn add -D unplugin-vue-router
# 或
pnpm add -D unplugin-vue-router

2. 配置 Vite

在你的 vite.config.ts 中引入并配置插件。关键点：VueRouter() 必须放在 vue() 插件之前。

vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import VueRouter from "unplugin-vue-router/vite"; // 引入插件

export default defineConfig({
  plugins: [
    // 配置 unplugin-vue-router
    VueRouter({
      /* 插件选项，例如 routesFolder: 'src/pages' */
    }),
    vue(), // 确保 vue() 在 VueRouter() 之后
  ],
});

3. 更新 TypeScript 配置

为了让 TypeScript 识别自动生成的路由类型，在 env.d.ts 或类似类型声明文件中添加以下引用：

env.d.ts
/// <reference types="vite/client" />
/// <reference types="unplugin-vue-router/client" /> // 添加这行

4. 修改路由文件

你原本手动创建路由的文件（通常是 src/router/index.ts）可以简化为：

src/router/index.ts
// 注意是从 vue-router/auto 导入
import { createRouter, createWebHistory } from "vue-router/auto"; 
// 插件会自动生成 routes 数组
import { routes } from "vue-router/auto-routes";

const router = createRouter({
  history: createWebHistory(),
  routes, // 使用自动生成的路由配置
});

export default router;

5. 确保 App.vue 使用 RouterView

你的 src/App.vue 需要包含 <RouterView /> 来显示页面组件。

App.vue
<template>
  <RouterView />
</template>

📝 使用自动生成的路由

配置完成后，src/pages 目录下的 .vue 文件会自动转换为路由。

1. 基本路由

src/pages/index.vue 对应路由 /
src/pages/about.vue 对应路由 /about。

2. 动态路由

使用方括号命名文件可以定义动态路由。

src/pages/users/[id].vue 生成路由 /users/:id。在组件内可通过 const { id } = useRoute().params 获取参数。
可选参数使用双括号，如 [[id]], 生成路由 /users/:id?。在组件内可通过 const { id } = useRoute().query 获取参数。

3. 嵌套路由

创建父子目录结构，并在父组件中使用 <router-view>。

例如：

src/pages/parent.vue 和 src/pages/parent/child.vue 会生成嵌套路由 /parent/child。父组件 parent.vue 中需要包含 <router-view/> 来渲染子组件。

4. 404 路由

创建一个文件名为 [...404].vue 的组件，它会被用来匹配所有未定义的路由，通常作为 404 页面使用。

⚙️ 自定义路由元信息

你可以使用 definePage 宏为页面添加路由元信息（meta），例如页面标题、所需的认证权限等。

<script setup>
definePage({
  meta: {
    requiresAuth: true, // 自定义元信息
    title: "用户主页",
  },
});
// 或者使用从外部导入的变量（插件支持）
import { appName } from "@/constants";
definePage({
  meta: {
    title: `首页 - ${appName}`,
  },
});
// 如果需要根据路由状态动态定义元信息，可使用回调函数
definePage({
  meta: (router) => ({
    title: `项目: ${router.currentRoute.value.query.code || "默认标题"}`,
  }),
});
</script>

为了让 TypeScript 识别这些自定义的 meta 字段，你需要进行类型扩展。创建一个类型声明文件（如 src/types/typed-router.d.ts）：

src/types/typed-router.d.ts
import "vue-router/auto-routes";

declare module "vue-router/auto-routes" {
  interface RouteMeta {
    /**
     * 页面标题
     */
    title?: string;
    /**
     * 是否需要认证
     */
    requiresAuth?: boolean;
    // ... 其他你需要的字段
  }
}

⚠️ 注意事项

1. 插件顺序

在 vite.config.ts 中，VueRouter() 插件必须放在 vue() 插件之前。

2. 自定义路由

如果自动生成的路由无法满足特殊需求（如非常特殊的路径或复杂逻辑），你仍然可以在 routes 数组中手动添加自定义路由，并与自动生成的路由一起使用。

src/router/index.ts
import { createRouter, createWebHistory } from "vue-router/auto";
import { routes } from "vue-router/auto-routes";
// 引入自定义组件
import CustomComponent from "@/views/CustomComponent.vue";

const router = createRouter({
  history: createWebHistory(),
  routes: [
    ...routes, // 展开自动生成的路由
    // 添加自定义路由
    {
      path: "/custom",
      component: CustomComponent,
      meta: { requiresAuth: false },
    },
  ],
});

export default router;

3. Data Loaders

一些高级功能（如 Data Loaders）仍标记为实验性，API 可能发生变化，在生产环境中使用需留意。

Data Loaders 主要用来在页面正式渲染前加载数据，确保数据的及时和准确性。

如果你使用了实验性的 Data Loaders 功能并在动态路由（如 [id].vue）中，为了确保参数变化时数据加载器能重新执行，必须将 Data Loader 从页面组件中导出。

💡 核心优势

Unplugin Vue Router 的核心优势在于：

开发效率提升：无需手动编写和维护路由配置文件，文件即路由。
类型安全：与 TypeScript 无缝集成，提供优秀的类型提示和自动补全，减少错误。
约定优于配置：遵循简单的文件命名约定即可支持动态路由、嵌套路由、404 路由等复杂场景。
热更新支持：在开发过程中，添加、删除或修改页面文件都会自动更新路由配置。

希望这份基础使用说明能帮助你快速上手 Unplugin Vue Router，享受更流畅的路由开发体验。更详细的配置和高级用法请参考其官方文档。

更新日志

2025/9/27 17:16

查看所有更新日志

1eb9b-docs(Javascript): 更新Generator生成器函数文档内容于 2025/9/27