61. Vue Router 4.x安装配置

📖 概述

Vue Router是Vue.js官方的路由管理器，用于构建单页应用(SPA)。Vue Router 4.x是为Vue 3设计的最新版本，提供了更强大的路由功能和更好的TypeScript支持。本集将深入讲解Vue Router 4.x的安装、配置和基础使用，包括路由实例创建、路由映射配置、组件注册、路由视图渲染等核心概念，帮助你快速上手Vue 3的路由系统。

✨ 核心知识点

1. Vue Router 4.x简介

Vue Router 4.x的新特性

• 完全适配Vue 3的Composition API
• 更好的TypeScript支持
• 组合式API路由函数（useRouter, useRoute）
• 支持路由元信息类型扩展
• 更灵活的路由配置
• 支持异步组件和懒加载
• 新增导航守卫API
• 更好的性能优化

Vue Router 4.x与Vue 3的关系

• Vue Router 4.x是Vue 3官方推荐的路由解决方案
• 与Vue 3的响应式系统深度集成
• 支持Vue 3的SFC (Single-File Component) 语法
• 与Composition API无缝配合

2. 安装Vue Router 4.x

1. 使用Vite创建Vue 3 + Vue Router项目

# 使用Vite创建项目时选择Vue Router
npm create vite@latest my-vue-app -- --template vue-ts
# 然后在配置选项中选择添加Vue Router

2. 手动安装Vue Router 4.x

# 在现有Vue 3项目中安装
npm install vue-router@4

3. 验证安装

# 查看Vue Router版本
npm list vue-router

3. 基础配置

1. 创建路由配置文件

在src目录下创建router目录，并创建index.ts文件：

// src/router/index.ts
import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router'
import HomeView from '../views/HomeView.vue'

// 定义路由配置
const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    name: 'home',
    component: HomeView
  },
  {
    path: '/about',
    name: 'about',
    // 懒加载组件
    component: () => import('../views/AboutView.vue')
  }
]

// 创建路由实例
const router = createRouter({
  // 使用HTML5 History模式
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

export default router

2. 配置主应用入口

在main.ts中注册路由：

// 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')

3. 配置路由视图

在App.vue中添加路由视图组件：

<!-- src/App.vue -->
<template>
  <div>
    <nav>
      <router-link to="/">首页</router-link> |
      <router-link to="/about">关于</router-link>
    </nav>
    <!-- 路由出口，渲染匹配的组件 -->
    <router-view />
  </div>
</template>

<style>
nav {
  padding: 30px;
}

nav a {
  font-weight: bold;
  color: #2c3e50;
}

nav a.router-link-exact-active {
  color: #42b983;
}
</style>

4. 创建路由组件

创建views目录，并创建路由组件：

<!-- src/views/HomeView.vue -->
<template>
  <div>
    <h1>首页</h1>
    <p>欢迎来到Vue Router 4.x的世界！</p>
  </div>
</template>

<script setup lang="ts">
// Home组件逻辑
</script>

<style scoped>
/* Home组件样式 */
</style>

<!-- src/views/AboutView.vue -->
<template>
  <div>
    <h1>关于我们</h1>
    <p>这是一个使用Vue Router 4.x构建的单页应用。</p>
  </div>
</template>

<script setup lang="ts">
// About组件逻辑
</script>

<style scoped>
/* About组件样式 */
</style>

4. 路由模式配置

1. HTML5 History模式

// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  // HTML5 History模式
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

• 优点：URL更美观，不包含#
• 缺点：需要服务器配置支持，否则刷新页面会404
• 适用场景：生产环境，需要SEO优化的应用

2. Hash模式

// src/router/index.ts
import { createRouter, createWebHashHistory } from 'vue-router'

const router = createRouter({
  // Hash模式
  history: createWebHashHistory(import.meta.env.BASE_URL),
  routes
})

• 优点：不需要服务器配置，兼容性好
• 缺点：URL包含#，不够美观
• 适用场景：开发环境，或不需要SEO的应用

3. 内存模式

// src/router/index.ts
import { createRouter, createMemoryHistory } from 'vue-router'

const router = createRouter({
  // 内存模式
  history: createMemoryHistory(),
  routes
})

• 优点：适合测试环境，不依赖浏览器URL
• 缺点：页面刷新后状态丢失
• 适用场景：测试环境，或非浏览器环境

5. TypeScript配置

1. 路由配置类型

使用RouteRecordRaw类型定义路由配置：

import { RouteRecordRaw } from 'vue-router'

const routes: Array<RouteRecordRaw> = [
  // 路由配置
]

2. 扩展路由元信息类型

创建src/router/types.ts文件，扩展路由元信息类型：

// src/router/types.ts
import 'vue-router'

// 扩展路由元信息类型
declare module 'vue-router' {
  interface RouteMeta {
    // 路由标题
    title?: string
    // 是否需要认证
    requiresAuth?: boolean
    // 权限要求
    permissions?: string[]
    // 菜单图标
    icon?: string
    // 是否在菜单中显示
    showInMenu?: boolean
  }
}

3. 使用扩展后的元信息

// src/router/index.ts
const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    name: 'home',
    component: HomeView,
    meta: {
      title: '首页',
      icon: 'home',
      showInMenu: true
    }
  },
  {
    path: '/about',
    name: 'about',
    component: () => import('../views/AboutView.vue'),
    meta: {
      title: '关于',
      icon: 'info',
      showInMenu: true,
      requiresAuth: true
    }
  }
]

6. 路由配置最佳实践

1. 路由模块化

将不同功能模块的路由分离到不同文件中：

// src/router/modules/user.ts
import { RouteRecordRaw } from 'vue-router'

const userRoutes: Array<RouteRecordRaw> = [
  {
    path: '/user',
    name: 'user',
    component: () => import('../../views/user/UserLayout.vue'),
    children: [
      {
        path: 'profile',
        name: 'userProfile',
        component: () => import('../../views/user/ProfileView.vue')
      },
      {
        path: 'settings',
        name: 'userSettings',
        component: () => import('../../views/user/SettingsView.vue')
      }
    ]
  }
]

export default userRoutes

// src/router/index.ts
import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router'
import HomeView from '../views/HomeView.vue'
import userRoutes from './modules/user'

const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    name: 'home',
    component: HomeView
  },
  // 合并模块化路由
  ...userRoutes
]

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

export default router

2. 路由组件懒加载

使用动态import实现路由组件懒加载：

const routes: Array<RouteRecordRaw> = [
  {
    path: '/about',
    name: 'about',
    // 懒加载组件
    component: () => import('../views/AboutView.vue')
  }
]

3. 路由命名规范

• 使用小写字母和连字符(-)命名路由路径
• 使用驼峰命名法命名路由名称
• 保持路由名称与组件名称一致

const routes: Array<RouteRecordRaw> = [
  {
    path: '/user-profile', // 路径使用连字符
    name: 'userProfile', // 名称使用驼峰命名
    component: UserProfileView // 组件名称与路由名称对应
  }
]

7. 运行与测试

1. 启动开发服务器

npm run dev

2. 访问应用

打开浏览器访问：http://localhost:5173

3. 测试路由功能

• 点击导航链接，查看页面切换
• 手动修改URL，查看路由匹配
• 测试页面刷新，确保路由正常工作

📝 最佳实践

1. 路由配置集中管理

   • 将路由配置集中在router目录下
   • 使用模块化管理复杂应用的路由

2. 使用TypeScript类型

   • 始终使用RouteRecordRaw类型定义路由配置
   • 扩展路由元信息类型，提高类型安全性

3. 实现路由懒加载

   • 对所有路由组件使用懒加载
   • 合理划分代码块，优化加载性能

4. 选择合适的路由模式

   • 开发环境使用Hash模式，无需服务器配置
   • 生产环境使用History模式，提高URL美观度

5. 配置路由元信息

   • 使用元信息存储路由的附加信息
   • 用于权限控制、菜单生成等场景

6. 保持路由命名规范

   • 统一的命名规范有助于团队协作
   • 提高代码的可读性和可维护性

7. 实现错误路由处理

   • 配置404路由，处理未匹配的URL
   • 提供友好的错误页面

8. 添加路由加载状态

   • 实现路由切换时的加载动画
   • 提高用户体验

💡 常见问题与解决方案

1. 页面刷新后404

   • 原因：使用History模式时，服务器未配置回退路由
   • 解决方案：
     • Nginx配置：添加try_files $uri $uri/ /index.html;
     • Apache配置：启用mod_rewrite，添加.htaccess文件
     • 或切换到Hash模式

2. 路由懒加载失败

   • 原因：动态import语法不支持
   • 解决方案：
     • 确保使用支持ES模块的构建工具（如Vite）
     • 检查TypeScript配置，启用module: "ESNext"

3. TypeScript类型错误

   • 原因：路由配置类型不匹配
   • 解决方案：
     • 使用RouteRecordRaw类型定义路由
     • 扩展路由元信息类型
     • 检查组件导入路径是否正确

4. 路由导航失败

   • 原因：导航守卫阻止了导航
   • 解决方案：
     • 检查导航守卫的逻辑
     • 使用router.push().catch()捕获导航错误

5. 嵌套路由不显示

   • 原因：父组件中未添加<router-view>
   • 解决方案：在父组件模板中添加<router-view>标签

📚 进一步学习资源

• Vue Router 4.x官方文档
• Vue Router 4.x GitHub仓库
• Vue 3 + Vue Router 4.x教程
• TypeScript官方文档
• Vite官方文档

🎯 课后练习

1. 基础练习

   • 使用Vite创建一个Vue 3 + Vue Router 4.x项目
   • 配置基本的路由结构，包括首页和关于页
   • 实现路由导航和页面切换

2. 进阶练习

   • 配置路由模块化，分离不同功能模块的路由
   • 实现路由懒加载，优化应用性能
   • 扩展路由元信息类型，添加自定义字段

3. 实战练习

   • 构建一个包含多个页面的单页应用
   • 实现嵌套路由结构
   • 配置History模式，并在本地服务器测试

4. TypeScript练习

   • 为路由配置添加完整的TypeScript类型
   • 扩展路由元信息类型
   • 实现类型安全的路由导航

通过本集的学习，你已经掌握了Vue Router 4.x的安装、配置和基础使用，包括路由实例创建、路由映射配置、组件注册、路由视图渲染等核心概念。在实际项目中，合理配置和使用Vue Router 4.x，能够构建出功能完整、性能优良的单页应用。下一集我们将深入学习路由配置与嵌套路由，进一步提升Vue 3路由系统的使用能力。