Vue3 怎么安装和配置 Router？从基础到进阶一次讲明白

咱先想啊，Vue3 项目里为啥非得用 Router？

做前端项目时,尤其是单页应用（SPA），页面切换没法像多页应用那样直接跳转 HTML 文件，要是没有路由，想实现“点导航栏切换页面”“商品详情页根据 ID 展示不同内容”这类需求，得自己写一堆逻辑控制组件显示隐藏，还得手动改 URL、处理浏览器前进后退……这时候 Router 就像“交通指挥官”，帮咱管理页面跳转、组件加载，还能做权限控制、传参这些事儿。

举个实际场景：做博客项目时，点“首页”“文章列表”“关于我”要切换对应组件，URL 也得跟着变；点文章标题进入详情页，URL 里得带文章 ID；个人中心页面只有登录后才能进……这些需求 Router 都能轻松搞定，既提升开发效率，也让用户体验更流畅。

要是用脚手架创建项目的时候，想直接把 Router 集成进去，该咋操作？

现在主流脚手架有 Vue CLI 和 Vite，两种方式集成 Router 的流程不太一样，分开说：

用 Vue CLI 创建时集成 Router

打开命令行,输入 vue create 项目名，选择 “Manually select features”（手动选择功能），接下来勾选项里找到 “Router”，按空格选中，再按回车，后续步骤选 Vue3 版本（3.x”），再选路由模式（一般选 History 模式，后续部署注意配置就行），等项目创建完，src 文件夹下会自动多一个 router 文件夹，里面的 index.js 已经配好基本路由结构，main.js 里也自动加了 app.use(router) 的代码，直接能用！

用 Vite 创建时集成 Router

现在很多人喜欢用 Vite，因为启动快、打包快，命令行输入 npm create vue@latest（或 yarn create vue），过程中会碰到问题 “Would you like to add Vue Router for Single Page Application development?” ，选 “YES” 就行，创建完项目后，src 下同样有 router 文件夹，index.js 里的配置更简洁，main.js 也自动引入并注册了 Router，直接写页面路由就行~

已经建好的 Vue3 项目，手动加 Router 咋操作？

要是项目一开始没集成 Router，后来想加上，得手动走流程，步骤不难：

第一步：安装 Router 依赖

打开命令行,进入项目根目录，执行 npm install vue-router@4（Vue3 对应 Router 的 4.x 版本，版本对应错了会疯狂报错！Vue3 用 Router 3.x 就会不兼容）。

第二步：新建路由配置文件

在 src 文件夹下新建 router 文件夹，里面创建 index.js，写入以下代码：

// 导入 Router 核心方法和组件
import { createRouter, createWebHistory } from 'vue-router'
// 导入要渲染的页面组件（也可以后面用懒加载）
import HomeView from '../views/HomeView.vue'
// 定义路由规则数组
const routes = [
  {
    path: '/', // 访问根路径时
    name: 'home', // 路由名称（可选，方便编程式导航）
    component: HomeView // 渲染的组件
  },
  {
    path: '/about',
    name: 'about',
    // 懒加载：访问时才加载组件，减少首屏体积
    component: () => import('../views/AboutView.vue') 
  }
]
// 创建 Router 实例
const router = createRouter({
  history: createWebHistory(), // History 模式（URL 好看但需后端配置）
  // 怕部署麻烦？也可用 Hash 模式：createWebHashHistory()，URL 带 #
  routes // 上面定义的路由规则
})
export default router // 导出供 main.js 使用

第三步：在 main.js 里注册 Router

打开 src/main.js，引入并注册 Router：

import { createApp } from 'vue'
import App from './App.vue'
import router from './router' // 导入刚写的路由配置
const app = createApp(App)
app.use(router) // 注册 Router 插件
app.mount('#app')

第四步：在 App.vue 里加路由出口和导航

打开 src/App.vue，在模板里加 <router-view>（路由组件渲染的地方）和 <router-link>（导航链接，比 a 标签更智能）：

<template>
  <div class="nav">
    <!-- 导航链接，to 属性指定路径 -->
    <router-link to="/">首页</router-link> | 
    <router-link to="/about">lt;/router-link>
  </div>
  <!-- 路由组件会渲染到这里 -->
  <router-view></router-view>
</template>
<style>
.nav {
  padding: 10px;
}
</style>

到这一步,手动安装 Router 就完成啦！启动项目，点导航栏就能看到组件切换~

Router 基本配置里，这些关键步骤得注意啥？

配置 Router 时，有几个点容易踩坑，逐个拆解：

选择 History 模式还是 Hash 模式？

• createWebHistory()：URL 长这样 http://xxx.com/about，好看但部署时需要后端配合（所有路由请求都指向 index.html，否则刷新页面会 404），适合正式项目，用户体验好。
• createWebHashHistory()：URL 长这样 http://xxx.com/#/about，有个 # 号，兼容性强（老浏览器也支持），部署不用额外配置，但 URL 没那么美观，适合快速原型开发或对 URL 颜值要求不高的项目。

路由规则（routes 数组）咋写？

每个路由对象里的 path 是访问路径，component 是对应组件，还能玩这些花样：

• 重定向（redirect）：比如访问 /old-path 时自动跳转到 /new-path：

  {
    path: '/old-path',
    redirect: '/new-path'
  }

• 嵌套路由（children）：用户中心”下有“个人资料”“我的订单”两个子页面，需要在父组件里加 <router-view> 显示子组件：

  {
    path: '/user',
    component: UserLayout, // 父组件，里面得有 <router-view>
    children: [
      {
        path: 'profile', // 访问 /user/profile 时
        component: UserProfile
      },
      {
        path: 'orders',
        component: UserOrders
      }
    ]
  }

组件导入咋选？同步还是异步？

• 同步导入：像 import HomeView from '../views/HomeView.vue'，项目启动时就加载组件，适合首屏必须的组件。
• 异步导入（懒加载）：像 component: () => import('../views/AboutView.vue')，访问对应路由时才加载组件，能大幅减少首屏加载时间，还能给 webpack 加注释分组，/* webpackChunkName: "about" */，让打包后的文件更清晰。

安装 Router 后，常见报错咋解决？

刚接触 Router 时，碰到报错别慌，大多是小问题，看几个高频场景：

报错“Uncaught Error: Router is not installed”

原因：Router 没在 main.js 里注册，检查 app.use(router) 是不是漏写了，或者导入路由文件时路径写错了（./router 写成 ../router）。

点击导航后页面没变化

可能是这俩原因：

• <router-view> 没加：得在 App.vue（或父组件）里放 <router-view>，否则路由组件没地方渲染。
• 组件路径写错：../views/AboutView.vue 写成 ./views/AboutView.vue，或者组件文件名大小写不对（Vue 对路径大小写敏感）。

重复点击同一路由，报错“NavigationDuplicated”

点同一个 <router-link> 或重复调用 router.push 时，Router 会抛这个错，解决方法：在 router/index.js 里重写 push 方法，捕获错误：

const router = createRouter({ ... })
// 重写 push，避免重复导航报错
const originalPush = router.push
router.push = function push(location, onResolve, onReject) {
  if (onResolve || onReject) {
    return originalPush.call(this, location, onResolve, onReject)
  }
  return originalPush.call(this, location).catch(err => err)
}
export default router

动态路由参数拿不到

比如路由是 /user/:id，想在组件里拿 id，得用 useRoute 钩子（Vue3 组合式 API）：

<template>
  <div>用户 ID：{{ route.params.id }}</div>
</template>
<script setup>
import { useRoute } from 'vue-router'
const route = useRoute() // 获取当前路由信息
</script>

Router 进阶玩法，哪些值得试试？

基础功能玩熟后,这些进阶技巧能让项目更专业：

动态路由匹配：根据 URL 参数渲染不同内容

比如做商品详情页,路由定义成 /product/:id，组件里用 useRoute().params.id 拿 ID，再发请求获取对应商品数据，这样一个组件就能适配所有商品详情，不用写 N 个组件~

路由守卫：控制页面访问权限

个人中心”页面只有登录用户能进，用 全局前置守卫（router.beforeEach） 拦截：

// router/index.js
import { useStore } from 'vuex' // 假设用 Vuex 存用户状态
router.beforeEach((to, from, next) => {
  const store = useStore()
  // 检查路由元信息里的 requiresAuth
  if (to.meta.requiresAuth && !store.state.user.isLogin) {
    next('/login') // 没登录就跳登录页
  } else {
    next() // 放行
  }
})
// 路由规则里加 meta
{
  path: '/profile',
  component: UserProfile,
  meta: { requiresAuth: true } // 需要登录
}

路由懒加载 + 分组：优化打包体积

把组件按功能分组,比如用户相关的组件都放到“user”分组里，打包时会生成单独的 chunk，访问时再加载：

{
  path: '/user/profile',
  component: () => import(/* webpackChunkName: "user" */ '../views/UserProfile.vue')
},
{
  path: '/user/orders',
  component: () => import(/* webpackChunkName: "user" */ '../views/UserOrders.vue')
}

路由过渡动画：让页面切换更丝滑

给 <router-view> 包一层 <Transition> 组件，加过渡动画：

<template>
  <Transition name="fade" mode="out-in">
    <router-view></router-view>
  </Transition>
</template>
<style>
/* 淡入淡出动画 */
.fade-enter-from, .fade-leave-to {
  opacity: 0;
}
.fade-enter-active, .fade-leave-active {
  transition: opacity 0.5s;
}
</style>

Vue3 里装 Router 不管是脚手架集成还是手动添加，核心都是“装依赖→配路由→注册→加导航和出口”，遇到问题先看报错信息，结合路由模式、组件路径、注册流程这些点排查，玩熟基础后，试试动态路由、守卫、懒加载这些进阶功能，项目体验和性能能更上一层楼~

要是你还有具体场景的问题,路由守卫里咋结合 Pinia 做权限？”“History 模式部署到 Nginx 咋配置？”，评论区喊我，咱再展开唠~