Vue Router

Vue.js 官方路由解决方案，为 Vue 应用提供声明式的组件导航与文件系统路由能力。

技术简介说明

Vue Router 是 Vue.js 官方维护的路由库，由 Vue 核心团队成员开发和维护。它与 Vue.js 深度集成，提供组件嵌套、过渡动效、数据获取等功能，是构建 Vue 单页应用（SPA）的标准方案。2026 年 3 月发布的 Vue Router 5.0 将 unplugin-vue-router 的文件系统路由能力整合进核心包，带来了原生文件路由约定、实验性数据加载 API 和增强的 TypeScript 类型推导，标志着 Vue Router 从传统配置式路由向现代文件系统路由的重要演进。

Vue Router 的设计理念强调简洁和约定优于配置。通过 <router-view> 和 <router-link> 两个核心组件即可完成大部分路由需求，同时提供命名视图、嵌套路由、路由懒加载、导航守卫等高级能力。Vue Router 5 延续了"无破坏性升级"的理念——对于未使用文件系统路由的 Vue Router 4 用户，升级几乎零成本；对于 unplugin-vue-router 用户，则只需调整导入路径。其 API 设计保持与 Vue 一致的开发体验，无论是 Options API 还是 Composition API 都能无缝使用。

作为 Vue 生态的核心组件，Vue Router 与 Vue CLI、Vite、Pinia 等工具深度集成，是 Vue 项目开发中的必选项。全球数百万 Vue 应用依赖 Vue Router 进行页面路由管理。Vue Router 5 的发布进一步巩固了其在 Vue 生态中的核心地位，并为 Vue Router 6（将仅支持 ESM 并移除废弃 API）铺平了道路。

基本信息

• 官网：https://router.vuejs.org/
• GitHub：https://github.com/vuejs/router
• License：MIT
• 最新版本：v5.1.0（2026 年 5 月 28 日）
• 主要维护者/公司：Eduardo San Martin Morote（Vue 核心团队）、尤雨溪（Evan You）

快速上手

安装

# Vue Router 5（推荐，2026 年最新稳定版）
npm install vue-router@5
pnpm add vue-router@5
yarn add vue-router@5
 
# Vue Router 4（仍受支持，适用于 Vue 3）
npm install vue-router@4
 
# 注意：Vue 3 使用 vue-router@4 或 @5，Vue 2 使用 vue-router@3（已停止维护）
# 新项目通常通过 create-vue 脚手架自动安装
npm create vue@latest my-vue-app
# 选择 Yes 到 "Would you like to add Vue Router?"

基础配置

传统配置式路由（Vue Router 4/5 通用）

// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
import type { RouteRecordRaw } from 'vue-router'
 
const routes: RouteRecordRaw[] = [
  {
    path: '/',
    name: 'Home',
    component: () => import('../views/HomeView.vue'),
  },
  {
    path: '/about',
    name: 'About',
    component: () => import('../views/AboutView.vue'),
  },
  {
    path: '/user/:id',
    name: 'UserDetail',
    component: () => import('../views/UserDetail.vue'),
    props: true, // 将路由参数作为 props 传递给组件
  },
]
 
const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes,
})
 
export default router

文件系统路由（Vue Router 5 新增，原 unplugin-vue-router）

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import VueRouter from 'unplugin-vue-router/vite' // Vue Router 5 内置
 
export default defineConfig({
  plugins: [
    VueRouter({
      // 路由文件目录
      routesFolder: 'src/pages',
      // 生成的类型文件输出路径
      dts: 'src/typed-router.d.ts',
    }),
    vue(),
  ],
})

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
 
const app = createApp(App)
app.use(router)
app.mount('#app')

最小示例

<!-- src/App.vue -->
<template>
  <nav>
    <router-link to="/">首页</router-link>
    <router-link to="/about">关于</router-link>
  </nav>
  <router-view />
</template>

<!-- src/views/HomeView.vue -->
<template>
  <h1>首页</h1>
</template>
 
<script setup lang="ts">
import { useRouter, useRoute } from 'vue-router'
 
const router = useRouter()
const route = useRoute()
 
// 编程式导航
function goToAbout() {
  router.push('/about')
}
 
// 获取路由参数
console.log(route.params)
</script>

核心概念与架构

路由实例

Vue Router 通过 createRouter() 创建路由实例，接受 history 模式和路由表配置。history 模式支持 createWebHistory（HTML5 History）、createWebHashHistory（Hash）和 createMemoryHistory（内存，用于 SSR/测试）。

路由表定义

路由表是一个 RouteRecordRaw 数组，每个路由记录包含 path、name、component、children、meta 等字段。支持嵌套、命名视图、路由别名、路由重定向等高级配置。

文件系统路由（Vue Router 5）

Vue Router 5 将 unplugin-vue-router 整合进核心，支持基于文件目录结构自动生成路由配置。例如：

src/pages/
├── index.vue          → /
├── about.vue          → /about
├── user/
│   ├── index.vue      → /user
│   └── [id].vue       → /user/:id
└── posts/
    ├── index.vue      → /posts
    └── [slug].vue     → /posts/:slug

这种约定优于配置的方式大幅减少了手动维护路由表的负担，同时自动生成 TypeScript 类型定义，提供完整的路径类型推导。

响应式路由状态

Vue Router 4/5 的路由状态（currentRoute）是响应式的，在组件中通过 useRoute() 获取的路由信息会自动响应 URL 变化。这得益于 Vue 3 的 Composition API 和响应式系统。

导航守卫

Vue Router 提供三层导航守卫：

• 全局守卫：router.beforeEach、router.afterEach
• 路由独享守卫：路由配置中的 beforeEnter
• 组件内守卫：onBeforeRouteLeave、onBeforeRouteUpdate（Composition API）

动态路由匹配

支持 :id（动态段）、:id+（多段）、:id*（可选多段）等参数模式，底层使用正则表达式进行路径匹配。Vue Router 5.1 新增了"原始参数解析器"（raw param parsers）和可重复子段参数支持。

嵌套路由与布局

通过 children 配置嵌套路由，父组件中使用 <router-view /> 渲染子路由。命名视图 <router-view name="sidebar" /> 支持同一路由渲染多个视图。

路由元信息

meta 字段用于附加路由元数据（如权限、标题、过渡动画等），在导航守卫中读取并做出决策。Vue Router 5 增强了 definePage 宏的 params.path 类型推导和严格类型默认值。

数据加载（实验性）

Vue Router 5 引入了实验性的数据加载 API，允许将数据获取绑定到特定路由，在路由过渡前预取数据。该功能从 unplugin-vue-router 合并而来，通过 vue-router/experimental 命名空间导入。

核心特性

• 响应式路由状态：基于 Vue 3 响应式系统，路由信息自动追踪变化
• 文件系统路由：Vue Router 5 原生支持基于文件目录的路由自动生成（原 unplugin-vue-router）
• 嵌套路由：支持多层嵌套的 URL 与组件映射
• 导航守卫：全局、路由独享、组件内三层守卫机制
• 路由懒加载：动态导入组件，按需加载路由
• 过渡动效：与 <Transition> 组件集成，支持路由切换动画
• 命名视图：同一路由渲染多个独立视图
• 路由元信息（meta）：灵活的元数据附加机制
• 滚动行为控制：自定义路由切换时的滚动位置
• History 模式：HTML5 History 和 Hash 模式可选
• TypeScript 深度类型推导：Vue Router 5 增强了 definePage 参数类型、路由校验 schema、Volar 编辑器插件
• 实验性数据加载：路由级数据预取，绑定导航生命周期
• 路由校验 Schema：参数和查询的校验模式定义，缺少参数解析器时即时报错
• View Transition API 支持：原生支持浏览器视图过渡 API
• SSR 兼容：支持 Nuxt.js 等 SSR 框架集成

生态图

关键依赖

• Vue.js ≥ 3.2：核心框架依赖
• @vue/devtools-api：开发者工具集成（Vue Router 5 IIFE 构建不再内置，需单独引入）
• Vite（可选 peer dependency）：文件系统路由的 Vite 插件支持

Vue 生态整合

• Vite：官方推荐的构建工具，与 Vue Router 5 文件系统路由深度集成
• Pinia：Vue 官方状态管理库，可与路由守卫协同
• Vue CLI：传统脚手架，自动配置 Vue Router
• Nuxt.js 3/4：基于 Vue 3 的全栈框架，内置路由方案（基于 Vue Router）；Nuxt 4.4 包含自定义数据 fetcher 实例和构建/运行时性能改进

相关插件与扩展

• vue-router-layout：布局管理插件
• vue-gtag：Google Analytics 路由追踪
• vue-router-tab：标签页路由管理
• vue-router-mock：路由单元测试 mock 工具
• unplugin-vue-router：已整合进 Vue Router 5 核心，独立包仍可用于旧项目

开发工具

• Vue DevTools：浏览器扩展，路由状态可视化
• Volar 插件：Vue Router 5 提供增强的 Volar 编辑器支持，路由路径自动补全和类型检查

社区生态

• 大量 UI 框架（Element Plus、Vuetify、Naive UI）提供路由集成方案
• 丰富的权限控制方案（基于路由守卫）
• 多语言路由方案（vue-i18n 集成）
• 文件系统路由社区方案日益成熟

适用场景

• Vue 3 单页应用（SPA）：Vue Router 是构建 Vue SPA 的标准方案
• 后台管理系统：嵌套路由、路由鉴权、权限控制是典型需求
• 电商/内容平台：SSR + 路由优化、SEO 友好
• 多页面应用（MPA）：在 Vue 应用中嵌入多个独立页面
• 企业级 Web 应用：路由级代码分割、懒加载优化大型应用
• 渐进式 Web 应用（PWA）：与 Service Worker 配合的离线路由
• 移动端 Vue 应用：配合 Vant、NutUI 等移动端组件库
• 大型内容站点：文件系统路由约定减少配置维护成本，适合页面结构清晰的站点

开发与工程化

开发流程

# 创建项目（自动集成 Vue Router）
npm create vue@latest my-app
cd my-app
 
# 开发
npm run dev
 
# 构建
npm run build
 
# 预览构建结果
npm run preview

项目结构

src/
├── router/
│   └── index.ts          # 路由配置
├── pages/                # 文件系统路由页面（Vue Router 5）
│   ├── index.vue
│   ├── about.vue
│   └── user/
│       ├── index.vue
│       └── [id].vue
├── views/                # 页面组件（传统配置式）
│   ├── HomeView.vue
│   └── AboutView.vue
├── components/           # 公共组件
├── stores/               # Pinia 状态
├── typed-router.d.ts     # 自动生成的路由类型（Vue Router 5）
├── App.vue
└── main.ts

路由配置最佳实践

// ✅ 推荐：使用路由分组和懒加载
const routes: RouteRecordRaw[] = [
  {
    path: '/',
    component: () => import('../layouts/DefaultLayout.vue'),
    children: [
      { path: '', name: 'home', component: () => import('../views/HomeView.vue') },
      { path: 'about', name: 'about', component: () => import('../views/AboutView.vue') },
    ],
  },
  {
    path: '/admin',
    component: () => import('../layouts/AdminLayout.vue'),
    meta: { requiresAuth: true },
    children: [
      { path: '', name: 'admin', component: () => import('../views/admin/Dashboard.vue') },
      { path: 'users', name: 'admin-users', component: () => import('../views/admin/Users.vue') },
    ],
  },
]

鉴权实现

// router/index.ts
import { useUserStore } from '@/stores/user'
 
router.beforeEach(async (to, from) => {
  const userStore = useUserStore()
 
  if (to.meta.requiresAuth && !userStore.isAuthenticated) {
    // 未登录，重定向到登录页
    return {
      path: '/login',
      query: { redirect: to.fullPath },
    }
  }
 
  if (to.meta.roles && !to.meta.roles.includes(userStore.role)) {
    // 权限不足
    return { path: '/403' }
  }
})

测试

// 使用 Vitest + Vue Test Utils
import { mount } from '@vue/test-utils'
import { createRouter, createMemoryHistory } from 'vue-router'
 
const router = createRouter({
  history: createMemoryHistory(),
  routes: [
    { path: '/', component: HomeView },
    { path: '/about', component: AboutView },
  ],
})
 
test('navigates to about page', async () => {
  const wrapper = mount(App, {
    global: { plugins: [router] },
  })
  await router.push('/about')
  await router.isReady()
  expect(wrapper.text()).toContain('关于')
})

CI/CD 集成

• 标准 Vite 构建流程
• 部署到 Nginx 时需要配置 fallback：try_files $uri $uri/ /index.html
• SPA 部署到静态托管服务（Vercel、Netlify、GitHub Pages）
• 文件系统路由项目需确保 Vite 插件在 CI 环境中正确生成类型

性能与安全

性能特点

• 路由懒加载：按需加载路由组件，减少初始包体积
• 命名组件缓存：<KeepAlive> 缓存路由组件，避免重复渲染
• 预加载：router.beforeEach 中可预取数据；Vue Router 5 数据加载 API 支持路由级预取
• 树摇优化：Vue Router 4/5 完全支持 tree-shaking

优化建议

• 使用路由懒加载 component: () => import(...) 分割代码
• 合理使用 <KeepAlive> 缓存频繁切换的页面
• 在导航守卫中批量处理鉴权逻辑，避免串行 await
• 大列表使用虚拟滚动，避免路由切换卡顿
• 使用 scrollBehavior 优化滚动体验
• Vue Router 5 用户可启用文件系统路由减少手动配置开销

安全注意事项

• 路由鉴权不能替代服务端鉴权：前端路由守卫只是 UX 优化，真正的权限验证必须在服务端
• XSS 防护：路由参数中的用户输入需要经过转义
• 开放重定向：登录后的 redirect 参数需要验证，防止重定向到恶意站点
• 敏感信息：不要在路由 query/params 中传递敏感信息
• Vue Router 5 IIFE 构建变更：不再内置 @vue/devtools-api，需单独引入以避免安全隐患

已知性能瓶颈

• 大型路由表（200+ 路由）首次匹配可能较慢
• <router-link> 大量渲染时的 DOM 开销
• 深层嵌套路由的递归渲染
• 动态路由频繁增删的内存泄漏风险

技术对比

最佳实践

路由模块化

// ✅ 推荐：按功能模块拆分路由配置
// src/router/modules/user.ts
import type { RouteRecordRaw } from 'vue-router'
 
const userRoutes: RouteRecordRaw[] = [
  {
    path: '/user',
    component: () => import('@/layouts/UserLayout.vue'),
    children: [
      { path: 'profile', name: 'user-profile', component: () => import('@/views/user/Profile.vue') },
      { path: 'settings', name: 'user-settings', component: () => import('@/views/user/Settings.vue') },
    ],
  },
]
export default userRoutes
 
// src/router/index.ts
import userRoutes from './modules/user'
const router = createRouter({
  history: createWebHistory(),
  routes: [/* ... */...userRoutes],
})

过渡动效

<!-- App.vue -->
<template>
  <router-view v-slot="{ Component, route }">
    <transition :name="route.meta.transition || 'fade'" mode="out-in">
      <keep-alive :include="cachedViews">
        <component :is="Component" :key="route.path" />
      </keep-alive>
    </transition>
  </router-view>
</template>
 
<style>
.fade-enter-active, .fade-leave-active {
  transition: opacity 0.3s ease;
}
.fade-enter-from, .fade-leave-to {
  opacity: 0;
}
</style>

错误处理

// ✅ 推荐：全局错误处理
router.onError((error, to) => {
  if (error.message.includes('Failed to fetch dynamically imported module')) {
    // 懒加载失败（新版本部署后旧 chunk 不存在）
    window.location.href = to.fullPath
  }
})
 
// 404 兜底路由
const routes: RouteRecordRaw[] = [
  // ... 其他路由
  { path: '/:pathMatch(.*)*', name: 'NotFound', component: () => import('@/views/NotFound.vue') },
]

常见陷阱

• ❌ 不要在组件内使用 window.location 导航，使用 router.push
• ❌ 不要在 beforeEach 中执行耗时操作（阻塞导航）
• ❌ 不要将路由参数作为组件内部状态，应该用 props 或 computed
• ❌ 不要在未验证的情况下信任 to.query.redirect
• ❌ Vue Router 5 升级时不要忽略 IIFE 构建中 @vue/devtools-api 的移除

技术局限与边界

已知限制

• Vue 3 专属：v4/v5 只支持 Vue 3，Vue 2 需要使用 v3（已进入维护模式）
• 数据加载仍为实验性：不像 React Router 有成熟的 loader/action，Vue Router 5 的数据加载 API 仍处于实验阶段
• 无内置搜索参数验证：需要配合 Zod 等库手动实现（Vue Router 5 的路由校验 Schema 部分缓解）
• 类型安全路由路径有限：虽然 Vue Router 5 增强了类型推导，但相比 TanStack Router 的完整类型安全仍有差距

不适用场景

• Vue 2 新项目（已停止新功能开发）
• 非 Vue 项目（React、Svelte、Angular 等）
• 需要完整类型安全路由路径的 TypeScript 严格项目（考虑 TanStack Router）
• 极简路由需求（可能 wouter 更合适）
• 纯 SSR 应用（考虑 Nuxt 或 Remix）

迁移注意事项

• Vue Router 4 → 5：
  • 对于未使用 unplugin-vue-router 的用户，无破坏性变更（唯一例外：IIFE 构建不再包含 @vue/devtools-api）
  • 对于 unplugin-vue-router 用户，主要是导入路径变更：
    1. 卸载旧 unplugin-vue-router 依赖，升级核心到 v5
    2. Vite 插件导入指向新的核心路径
    3. 数据加载导入移至 vue-router/experimental 命名空间
    4. 工具函数和 Volar 插件导入移至新的核心路径
    5. 删除旧客户端类型引用
    6. 将生成的类型文件移入源码目录
• Vue 2 → Vue 3：Vue Router 3 → 4/5
  • new Router() → createRouter()
  • router.onReady() → router.isReady()
  • 组件内守卫从选项变为 Composition API（onBeforeRouteLeave）
  • $route、$router 通过 useRoute()、useRouter() 替代

学习资源

• 官方文档：https://router.vuejs.org/
• API 参考：https://router.vuejs.org/api/
• 安装指南：https://router.vuejs.org/installation
• 迁移指南（v4 → v5）：https://router.vuejs.org/guide/migration/v4-to-v5
• GitHub 仓库：https://github.com/vuejs/router
• 教程：
  • Vue.js 官方教程 - 路由章节
  • Vue Mastery - Vue Router 课程
  • Vue School - Vue Router 课程
• 社区资源：
  • Vue Land Discord
  • GitHub Discussions
  • Stack Overflow #vue-router
  • Vue.js 中文社区
• 视频：
  • Vue.js 官方 YouTube 频道
• 相关报道：
  • InfoQ - Vue Router 5: File-Based Routing into Core
  • State of Vue & Vite 2026: Amsterdam recap

2026 年现状

最新版本

• Vue Router 5.1.0（2026 年 5 月 28 日）：当前最新稳定版
• Vue Router 5.0.0（2026 年 3 月 4 日）：重大版本更新，整合文件系统路由
• Vue Router 4.x：仍受支持，适用于不需要文件系统路由的 Vue 3 项目

发展趋势

• 文件系统路由成为核心：Vue Router 5 将 unplugin-vue-router 整合进核心，文件系统路由成为官方推荐方案之一
• 数据加载 API 演进：实验性数据加载 API 将在后续版本中成熟，为 Vue Router 6 的完整数据层做准备
• TypeScript 类型推导增强：Vue Router 5.1 进一步增强了 definePage 参数类型、原始参数解析器等类型推导能力
• View Transition API 支持：原生支持浏览器视图过渡 API，提供更流畅的路由切换体验
• Vue Router 6 规划：将仅支持 ESM 并移除废弃 API，Vue Router 5 作为过渡版本
• Nuxt 4 协同：Nuxt 4.4 与 Vue Router 5 深度协同，提供更强大的全栈开发体验

社区活跃度

• GitHub Stars：~19k
• npm 周下载量：~400 万+
• 贡献者：400+
• 更新频率：每月 1-2 次版本更新
• Vue Router 5 的发布引发了社区广泛关注和讨论

未来路线图

• 数据加载 API 从实验性转为稳定
• 路由匹配性能持续优化
• TypeScript 类型推导进一步增强
• 与 Suspense 的更深集成
• View Transition API 的更完整支持
• Vue Router 6 的 ESM-only 迁移准备
• 社区插件生态的持续丰富