vue-router 3.x 安装指南：CDN、NPM、Vue CLI 插件与开发版构建全解析

vue-router 3.x 安装指南：CDN、NPM、Vue CLI 插件与开发版构建全解析

【免费下载链接】vue-router🚦 The official router for Vue 2项目地址: https://gitcode.com/gh_mirrors/vu/vue-router

导读

本文以 Vue 2 官方路由管理器 vue-router 的安装文档（docs/zh/installation.md）为主线，系统讲解四种获取与接入 vue-router 的方式：直接下载 / CDN 引入、NPM 包管理、Vue CLI 插件化添加，以及从源码构建开发版。读完本文你将掌握每种方式的使用场景、操作步骤与注意事项，并能结合仓库源码（src/install.js、package.json）理解Vue.use()自动安装机制的底层原理，为后续编写路由配置、守卫与动态匹配打好基础。

vue-router 是 Vue.js 2 的官方路由管理器，与 Vue 核心深度集成，支持嵌套路由、路由参数、导航守卫、HTML5 history / hash 两种模式等能力。当前仓库对应 vue-router 3.6.5 版本（见 package.json），下文所有命令与产物均以该版本为准。

一、直接下载 / CDN 引入

1.1 获取最新版或指定版本

vue-router 官方文档提供基于 NPM 的 CDN 链接：

https://unpkg.com/vue-router@3/dist/vue-router.js

上面的链接会始终指向 NPM 上发布的最新版本，适合快速体验；生产环境更推荐锁定版本号或 Tag，避免 CDN 内容意外变更：

https://unpkg.com/vue-router@3.6.5/dist/vue-router.js

也可以使用@3.0.0这类早期版本号。从当前仓库 package.json 的unpkg与jsdelivr字段可以看出，dist/vue-router.js正是为 CDN 场景准备的 UMD 构建产物：

"main": "dist/vue-router.common.js", "module": "dist/vue-router.esm.js", "unpkg": "dist/vue-router.js", "jsdelivr": "dist/vue-router.js"

仓库根目录的dist/目录中实际存在vue-router.js、vue-router.min.js、vue-router.esm.js、vue-router.esm.browser.js、vue-router.common.js与vue-router.mjs等产物，分别面向 script 标签、浏览器原生 ESM、打包工具 CommonJS 与 Node ESM 等不同消费场景。

1.2 在 Vue 之后加载，自动安装

用<script>标签引入时，必须先加载 Vue，再加载 vue-router：

<script src="/path/to/vue.js"></script> <script src="/path/to/vue-router.js"></script>

只要保证加载顺序正确，vue-router 会自动安装（在浏览器全局环境中，UMD 构建会调用install完成注册），无需额外调用Vue.use()。

从源码看，这个"自动安装"的入口位于 src/index.js 与 src/entries/cjs.js：src/index.js引入./entries/cjs并默认导出VueRouter，而 UMD 构建产物在浏览器中执行时会通过VueRouter.install挂载到全局 Vue。核心的install函数定义在 src/install.js，它负责注册全局混入（beforeCreate中初始化_routerRoot与_route）、在Vue.prototype上注入$router/$route属性、全局注册RouterLink/RouterView两个组件，并将路由守卫钩子的选项合并策略与created对齐。

1.3 手动在模块化工程中引入

如果使用 NPM 包但不走打包工具，也可以手动引入 ESM 版本并自行安装：

import Vue from 'vue' import VueRouter from 'vue-router' Vue.use(VueRouter)

二、NPM 安装与Vue.use()显式安装

2.1 安装命令

npm install vue-router

仓库当前版本为 3.6.5（对应 Vue 2.x）。如果你使用的是 npm 5+，package-lock.json会锁定精确版本；使用 yarn 的项目可执行等价的yarn add vue-router。

2.2 为什么模块化工程必须Vue.use()

与 CDN 的自动安装不同，在模块化工程（Webpack / Rollup 等）中，必须通过Vue.use()显式安装路由功能：

import Vue from 'vue' import VueRouter from 'vue-router' Vue.use(VueRouter)

原因在于：打包工具将 vue-router 作为普通 ES Module 引入后，它并不会自动感知宿主 Vue 实例，install必须被显式调用。Vue.use()会调用插件暴露的install方法，并保证同一插件只安装一次。

结合源码印证，src/install.js 的安装逻辑为：

export function install (Vue) { if (install.installed && _Vue === Vue) return install.installed = true _Vue = Vue // ... 全局混入、$router/$route 注入、组件注册 }

其中install.installed用于幂等保护——同一 Vue 构造函数只安装一次；而 src/router.js 中init方法也专门断言了install.installed，若未先执行Vue.use(VueRouter)就创建根实例，会得到 "not installed. Make sure to callVue.use(VueRouter)before creating root instance." 的警告。

安装完成后，需要把VueRouter实例传入根 Vue 实例：

const router = new VueRouter({ routes: [ { path: '/', component: Home } ] }) new Vue({ router, render: h => h(App) }).$mount('#app')

2.3 ESM 与命名导出

当前仓库还通过exports字段（package.json）暴露了子路径vue-router/composables（对应 composables.mjs），其中提供了useRouter、useRoute、useLink、onBeforeRouteUpdate、onBeforeRouteLeave等组合式 API，供在 Vue 2.7 + Composition API 场景下使用。此外，ESM 入口 src/entries/esm.js 还导出了version、isNavigationFailure、NavigationFailureType、START_LOCATION以及RouterLink/RouterView组件。

三、通过 Vue CLI 插件添加

如果你正在使用 Vue CLI 项目，可以以项目插件的形式添加 Vue Router：

vue add router

该命令会帮你：

• 自动生成Vue.use(VueRouter)及路由实例创建代码；
• 生成两个示例路由（通常是一个首页与一个 About 页面）供参考；
• 自动在main.js中接入路由实例。

重要警告：vue add router会覆盖你现有的App.vue（以及可能调整main.js等文件），因此在项目中执行该命令之前，请务必先备份这些文件。建议在 Git 工作区中确认当前改动已提交，或手动复制一份App.vue留存。

四、构建开发版（使用最新源码）

如果你需要使用尚未发布到 NPM 的最新开发版，需要从 GitHub 克隆仓库并自行构建：

git clone https://github.com/vuejs/vue-router.git node_modules/vue-router cd node_modules/vue-router npm install npm run build

几点说明：

• 克隆到node_modules/vue-router目录后，项目中已有的import VueRouter from 'vue-router'无需改动即可直接解析到本地源码构建产物，适合在本地方案中先行验证新功能。
• npm install安装全部开发依赖（Rollup、Babel、Flow、Jasmine、Nightwatch 等，见 package.json）。
• npm run build对应脚本node build/build.js（package.json），会借助 Rollup 打包出dist/下的全部产物（UMD、ESM、CommonJS、压缩版等），供不同场景消费。
• 构建完成后可运行npm run dev（node examples/server.js）启动本地示例服务器，仓库 examples 目录提供了从基本路由、嵌套路由到导航守卫、数据获取等大量可直接运行的示例。
• 若想跑完整测试，可执行npm test（依次执行 lint、Flow 类型检查、Jasmine 单元测试、Nightwatch 端到端测试与 TypeScript 类型测试）；其中单元测试用例位于 test/unit/specs，例如 node.spec.js 专门覆盖服务端 / 非浏览器环境下的安装与使用。

五、四种方式的选型建议

方式	适用场景	安装/引入方式	是否需要Vue.use()
CDN / 直接下载	快速原型、静态页、无构建工具	<script>标签	不需要（自动安装）
NPM	模块化工程（Webpack/Rollup/Vue CLI 等）	npm install vue-router	必须显式调用
Vue CLI 插件	已有 Vue CLI 项目	vue add router	CLI 自动生成
源码构建	尝鲜最新 dev 版、贡献代码	clone +npm run build	按 NPM 方式使用

无论采用哪种方式，接入后建议从仓库文档 docs/zh/guide/essentials 的"起步"与动态路由匹配章节继续，完成路由表定义与<router-link>/<router-view>的组装，即可运行第一个多页面 SPA。

【免费下载链接】vue-router🚦 The official router for Vue 2项目地址: https://gitcode.com/gh_mirrors/vu/vue-router