一、安装前得先明确这两个关键信息

terry 3周前 (09-06) 阅读数 49 #Vue

很多刚接触 Vue 开发的小伙伴，在搭建单页应用时都会碰到路由管理的问题，而 Vue Router 就是官方推荐的路由解决方案，但“Vue Router 该咋安装？不同项目场景下安装方式有啥区别？”这类问题经常让人犯难——毕竟项目有 Vue2 和 Vue3 的版本差异，还有用脚手架创建和手动搭建项目的不同情况，接下来咱们就把这些场景拆解开，一步步说清楚安装的门道，从环境确认到具体操作，再到踩坑解决，全流程梳理明白。

要装 Vue Router，得先搞清楚两个核心点：项目用的 Vue 版本 和 包管理工具。

先说 Vue 版本和 Vue Router 版本的对应关系：Vue2 必须搭配 vue-router@3.x 版本，Vue3 得用 vue-router@4.x 版本，要是版本对不上，安装后启动项目准报错，Vue2 硬装了 vue-router@4，控制台会疯狂提示「Vue.use() 要传入插件对象」这类错误，项目根本跑不起来。

再看包管理工具,常见的有 npm、yarn、pnpm，不同工具的安装命令有区别，但作用都是把 Vue Router 装到项目里，要是你项目里没有 package.json（比如纯手动写 HTML + JS 的小项目），得先执行 npm init -y 这类命令初始化包管理配置，否则没法用命令行安装。

Vue2 项目里装 Vue Router，分“脚手架创建”和“手动搭建”两种情况

Vue2 项目安装 Vue Router 的逻辑，会因为“项目是用脚手架生成还是手动搭建”产生差异，咱们逐个拆解。

用 Vue CLI 脚手架创建的项目咋装？

如果是用 vue create 项目名 生成的 Vue2 项目，安装步骤很清晰：

第一步：进入项目目录
打开终端，cd 到项目根目录（比如项目叫 my-vue2-app，就执行 cd my-vue2-app）。
第二步：执行安装命令
因为是 Vue2，要装 3.x 版本，用 npm 的话，执行 npm install vue-router@3；用 yarn 就执行 yarn add vue-router@3，等终端跑完，node_modules 里就有 Vue Router 了。

第三步：配置路由文件
在 src 文件夹下新建 router 文件夹，里面创建 index.js，代码模板如下：

import Vue from 'vue'
import VueRouter from 'vue-router'
// 假设要导入 Home 组件，路径根据自己项目结构调整
import Home from '../views/Home.vue'
// 解析 VueRouter 插件（必须步骤）
Vue.use(VueRouter)
// 定义路由规则
const routes = [
  {
    path: '/', // 根路径
    name: 'Home',
    component: Home // 对应的组件
  }
  // 还能添加其他路由，/about 之类的
]
// 创建路由实例
const router = new VueRouter({
  routes // 把上面定义的规则传进去
})
// 导出，方便其他文件引入
export default router

第四步：注入到 Vue 实例
打开 src/main.js，引入刚才的路由配置：

import Vue from 'vue'
import App from './App.vue'
import router from './router' // 引入路由配置
new Vue({
  router, // 把路由实例挂到 Vue 实例上
  render: h => h(App)
}).$mount('#app')

第五步：验证是否生效
在 App.vue 里添加 <router-view></router-view>（路由组件的渲染出口）和 <router-link to="/">回到首页</router-link>（跳转用的组件），然后执行 npm run serve 启动项目，看页面能不能正常显示 Home 组件、点击链接能不能跳转，能正常工作的话，说明安装配置成功！

手动搭建的 Vue2 项目咋装？

有些小伙伴没用地脚手架,自己手动建了 index.html、main.js 这些文件，这种情况安装步骤得灵活调整：

第一步：确保有 package.json
要是项目里没有 package.json，先在项目根目录执行 npm init -y，生成基础的包管理配置文件。
第二步：安装 Vue Router
执行 npm install vue-router@3（或 yarn/pnpm 对应命令），把 Vue Router 装到项目里。
第三步：配置路由文件
逻辑和脚手架项目差不多，但要注意文件路径和脚本引入方式，如果项目用 CDN 引入 Vue，Vue Router 也可以用 CDN（<script src="https://unpkg.com/vue-router@3/dist/vue-router.js"></script>），但更推荐用模块化方式（和脚手架一样用 import）。

举个例子,手动项目的 main.js 可能长这样：
```
import Vue from 'vue'
import App from './App.vue'
import router from './router'
new Vue({
  router,
  render: h => h(App)
}).$mount('#app')
```
但要注意：如果直接用浏览器打开 index.html，会因为模块化语法（import/export）报错，这时候要么用 webpack、vite 这类打包工具，要么改用 CDN 全局引入的方式，不过现在大部分项目都会用打包工具，所以按脚手架的配置逻辑走就行，重点是确保文件结构和引入路径正确。

Vue3 项目装 Vue Router，重点看“Vite”还是“Vue CLI”创建的

Vue3 对应 vue-router@4.x，安装和配置逻辑和 Vue2 有不少区别，而且现在很多新项目用 Vite 代替 Vue CLI，所以分场景说明。

Vite + Vue3 项目的安装流程

用 Vite 创建 Vue3 项目（命令是 npm create vite@latest 项目名 -- --template vue），安装步骤如下：

第一步：进入项目目录，安装依赖
cd 到项目根目录后，执行 npm install vue-router@4（yarn 用 yarn add vue-router@4，pnpm 用 pnpm add vue-router@4）。

第二步：配置路由文件
在 src 下新建 router 文件夹，创建 index.js，代码如下：

import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'
// 创建路由实例
const router = createRouter({
  // 路由模式：createWebHistory 对应 history 模式（路径好看但需要后端配置）；createWebHashHistory 是 hash 模式（路径带 #，不需要后端配置）
  history: createWebHistory(),
  routes: [
    {
      path: '/',
      name: 'Home',
      component: Home
    }
    // 其他路由规则...
  ]
})
export default router

第三步：注入到 Vue 应用实例
打开 src/main.js，代码如下：

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
const app = createApp(App)
app.use(router) // 挂载路由插件
app.mount('#app')

第四步：验证路由
和 Vue2 类似，在 App.vue 里加 <router-view></router-view> 和 <router-link to="/">Home</router-link>，然后执行 npm run dev 启动项目，看组件能不能渲染、链接能不能跳转。

这里要注意路由模式的选择：如果项目要部署到静态服务器（GitHub Pages），用 createWebHashHistory 更稳妥（否则 history 模式刷新页面会404）；如果后端能配置 rewrite 规则（Nginx 配 try_files），用 history 模式路径更美观。

Vue CLI 创建的 Vue3 项目安装

虽然 Vue CLI 现在更推荐用 Vite，但还有团队在维护老项目，所以也得讲讲，用 Vue CLI 创建 Vue3 项目（vue create 项目名，选择 Vue3 版本），安装步骤：

第一步：安装 vue-router@4
进入项目目录后，执行 npm install vue-router@4。
第二步：配置路由文件
和 Vite 项目的 router/index.js 几乎一样，因为核心逻辑是 Vue3 + vue-router@4 的 API，和构建工具（Vite 或 webpack，Vue CLI 用的是 webpack）关系不大。router/index.js 还是用 createRouter、createWebHistory 这些方法。
第三步：注入到 main.js
代码和 Vite 项目一致：
```
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
createApp(App).use(router).mount('#app')
```
验证方式也和 Vite 项目一样，重点是理解 Vue3 的 createApp 语法和 Vue2 的 new Vue 差异，路由配置本身的逻辑是通用的。

换包管理工具？npm、yarn、pnpm 安装命令差异

不同团队用的包管理工具不一样,所以得把常见工具的命令列清楚，避免“拿 npm 命令用 yarn 执行”这类低级错误。

npm 安装命令

Vue2 项目：npm install vue-router@3（依赖会写到 package.json 的 dependencies 里，因为路由是生产依赖）。
Vue3 项目：npm install vue-router@4。

如果安装时碰到依赖冲突（npm ERR! code ERESOLVE），可以试试先删了 node_modules 和 package-lock.json，然后重新 npm install，或者指定更精确的版本号（vue-router@3.6.5）。

yarn 安装命令

Vue2 项目：yarn add vue-router@3（会生成 yarn.lock 文件，锁定版本，团队协作时能避免版本不一致）。
Vue3 项目：yarn add vue-router@4。

yarn 的优势是安装速度有时候比 npm 快，lock 文件更严格，要是装完后项目跑不起来，先看 yarn.lock 里的版本是不是和 package.json 一致，不一致就删了 lock 文件重新 yarn install。

pnpm 安装命令

Vue2 项目：pnpm add vue-router@3。
Vue3 项目：pnpm add vue-router@4。

pnpm 是近几年流行的包管理工具，优点是节省磁盘空间（不同项目共享依赖）、安装速度快，如果团队用 pnpm，就用对应的命令，安装后如果报错，检查 .pnpm-store 是不是正常，或者换用 npm/yarn 试试，排除工具问题。

安装后必须做的配置和验证，少一步都可能白装

很多新手装完 Vue Router 就以为完事了，结果页面没反应——其实是配置和验证没做好，这部分要讲清楚“必须做的事”。

路由文件的基础结构得写对

Vue2 和 Vue3 的路由文件结构有差异，核心是创建路由实例的方式：

Vue2 用 new VueRouter({ routes })；
Vue3 用 createRouter({ history, routes })。

而且组件导入路径不能错,import Home from '../views/Home.vue'，得确保 Home.vue 真的在 views 文件夹里，并且用 export default 导出了组件。

必须把路由注入到 Vue 实例

Vue2 是在 new Vue({ router }) 里传 router 选项；Vue3 是 createApp(App).use(router)，少了这一步，路由插件就没被激活，<router-view> 和 <router-link> 这些组件也不会生效。

验证步骤要做全

启动项目后,先看控制台有没有报错（Unknown custom element: 」这类错误，说明路由没注入），然后手动输入路径（localhost:8080/ 或者 localhost:5173/），看组件能不能渲染；点 <router-link> 看能不能跳转；刷新页面看会不会404（如果是 history 模式要注意后端配置），要是这些都没问题，说明安装配置成功了。

安装时常见的“坑”和解决办法，避坑才能少熬夜

实际开发中,安装 Vue Router 很容易碰到各种“玄学问题”，这里总结几个高频坑和解决办法：

版本不兼容：Vue2 装了 vue-router@4

现象：启动项目后，控制台报错「Vue.use() requires a plugin object」或者「Cannot read properties of undefined (reading 'use')」。
原因：Vue2 和 vue-router@4 不兼容，API 差异导致插件无法解析。
解决：卸载当前版本，重新装对应版本，执行 npm uninstall vue-router，npm install vue-router@3。

路由模式导致部署后404（Vue3 的 history 模式）

现象：本地开发好好的，部署到服务器后，刷新页面就404。
原因：history 模式下，URL 没有，服务器不知道该把请求转发到 index.html，所以返回404。
解决：要么改用 hash 模式（把 createWebHistory 改成 createWebHashHistory）；要么让后端配置路由重写，Nginx 里加 try_files $uri $uri/ /index.html;。

包管理工具安装失败（依赖冲突）

现象：执行安装命令后，终端报错「ERESOLVE could not resolve」或者「conflicting peer dependencies」。
原因：项目依赖之间版本冲突，包管理工具无法自动解决。
解决：先删了 node_modules 和 package-lock.json（或 yarn.lock、pnpm-lock.yaml），然后重新安装；或者指定更精确的版本号（vue-router@3.6.5）；还可以换用其他包管理工具试试（npm 装不上换 yarn）。