1. 项目概述为什么Vue Router是Vue3项目的“导航大脑”如果你正在用Vue3开发一个稍微复杂点的应用比如一个后台管理系统或者一个内容网站你很快就会遇到一个核心问题如何管理页面用户点击一个菜单怎么切换到对应的组件浏览器的前进后退按钮怎么让它正常工作页面之间怎么传递参数这些看似基础的需求背后都需要一个专门的路由系统来支撑。Vue Router就是Vue生态中专为这个任务而生的官方路由库。在Vue3的时代它也跟着升级到了Vue Router 4虽然核心概念没变但在组合式APIComposition API的支持、TypeScript集成以及一些API设计上有了更现代化、更贴合Vue3开发习惯的用法。简单来说你可以把Vue Router理解为应用的“导航大脑”。它负责监听URL的变化根据你预先定义好的规则路由表找到对应的Vue组件并将其渲染到指定的位置通常是router-view。没有它你的单页面应用SPA就只是一堆静态组件的堆砌无法实现真正的页面跳转和状态管理。对于新手理解并掌握Vue Router是迈向Vue3实战开发的关键一步对于有Vue2经验的开发者了解Vue Router 4的变化则是平滑过渡的必修课。接下来我会以一个典型的后台管理系统为场景带你从零开始深入每一个细节把Vue Router在Vue3中的使用讲透。2. 环境搭建与基础配置从零创建一个带路由的Vue3项目2.1 项目初始化与Vue Router安装现在创建Vue3项目Vite是绝对的主流选择它速度快、配置简单。我们从头开始创建一个集成了Vue Router的项目。打开你的终端执行以下命令# 使用 npm 7 的额外双横线 npm create vuelatest my-vue-router-app # 或者使用 yarn yarn create vue my-vue-router-app # 或者使用 pnpm pnpm create vue my-vue-router-app这个命令会启动一个交互式的项目创建向导。你会被询问一系列问题这里是我们需要关注的选项Add TypeScript? 根据需求选择本文示例使用JavaScript。Add JSX Support? 选择No除非你明确需要使用JSX。Add Vue Router for Single Page Application development?务必选择 Yes。这是最关键的一步它会自动为我们安装vue-router包并生成基础的路由配置。Add Pinia for state management? 可选状态管理不是本文重点。Add Vitest for Unit Testing? 可选。Add an End-to-End Testing Solution? 可选。Add ESLint for code quality? 建议选择Yes保持代码规范。一路选择完毕后进入项目目录并安装依赖cd my-vue-router-app npm install # 或 yarn / pnpm install注意 如果你在一个已有的、没有安装Vue Router的Vue3项目中手动安装可以使用npm install vue-router4。但强烈推荐使用上述create vue脚手架它能生成最标准、最省心的初始配置。安装完成后观察项目结构你会发现多了一个src/router目录里面有一个index.js或index.ts文件。这就是我们路由系统的核心配置文件。2.2 路由配置文件深度解析让我们打开src/router/index.js看看脚手架为我们生成了什么import { createRouter, createWebHistory } from vue-router import HomeView from ../views/HomeView.vue const router createRouter({ // 1. 使用 HTML5 History 模式 history: createWebHistory(import.meta.env.BASE_URL), // 2. 定义路由表 routes: [ { path: /, name: home, component: HomeView }, { path: /about, name: about, // 路由级代码分割懒加载组件 component: () import(../views/AboutView.vue) } ] }) export default router我们来逐行拆解这个配置的核心createRouter 这是Vue Router 4的工厂函数用于创建路由实例。它接收一个配置对象。history模式createWebHistory()创建的是HTML5 History模式。它利用history.pushStateAPI让URL看起来像正常的路径如/about而不是带#的哈希模式如/#/about。这更美观对SEO也更友好。import.meta.env.BASE_URL是Vite提供的环境变量如果你的应用部署在子路径如https://example.com/my-app/它会自动处理基础路径。对比哈希模式 你可以使用createWebHashHistory()来启用哈希模式。它的优点是兼容性极好无需服务器额外配置。但URL中的#不太美观。对于现代浏览器History模式是首选。routes数组 这是路由表一个对象数组。每个对象定义一条路由规则。path 匹配的URL路径。可以是静态字符串/about也可以是动态段/user/:id。name 路由的唯一名称。在编程式导航或router-link中可以通过名称来引用路由这比硬编码路径更可靠尤其是在路径结构可能改变时。component 该路径下要渲染的组件。这里展示了两种方式直接导入component: HomeView。适用于核心、首屏必须的组件。懒加载推荐component: () import(../views/AboutView.vue)。这是通过动态导入实现的代码分割。当用户访问/about路径时才会加载AboutView.vue这个组件的代码。这能显著提升应用初始加载速度是构建大型应用的必备优化手段。这个路由实例创建后需要在主应用入口通常是src/main.js中被挂载到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)至此一个具备基本路由功能的Vue3应用就搭建好了。运行npm run dev你就能在页面中通过导航栏点击在Home和About页面间切换。3. 核心概念与组件实战router-link与router-view路由配置好了怎么在页面上用呢主要靠两个内置组件。3.1router-link声明式导航的利器在src/App.vue中你会看到类似这样的导航代码template nav router-link to/Home/router-link | router-link to/aboutAbout/router-link /nav router-view/ /templaterouter-link是用于替代原生a标签进行导航的组件。它的核心优势在于在单页面应用内部进行跳转不会触发浏览器整页刷新体验流畅。自动获取激活状态。当链接指向的路由被激活时组件会自动添加一个router-link-active的CSS类默认行为可配置方便你为当前选中的导航项设置高亮样式。router-link的to属性非常灵活路径字符串to/about带有路径的对象to{ path: /about }带有命名的路由对象更推荐to{ name: about }。这样做的好处是即使你后来修改了/about这个路径只要name不变所有引用它的链接都无需更改。带查询参数和哈希to{ path: /search, query: { q: vue }, hash: #results }实操心得 在大型项目中我强烈建议始终使用name进行导航。路径可能会因为业务调整而改变例如从/user改为/member但路由名称通常是业务逻辑的抽象如userProfile更稳定。这能极大减少因路径变更导致的链接失效问题。3.2router-view路由组件的渲染出口router-view是一个功能性组件它就像一个“占位符”或“窗口”。路由匹配到的组件将会被渲染在router-view所在的位置。你可以把它理解为一个动态的组件交换机。嵌套路由与多个router-view 这是Vue Router进阶使用的关键。一个复杂的应用界面通常是嵌套的。例如一个后台管理系统顶部有导航栏左侧有菜单栏中间是主要内容区。这就可以通过嵌套路由来实现。定义嵌套路由 在路由配置中通过children属性来定义子路由。// router/index.js { path: /dashboard, name: dashboard, component: DashboardLayout, // 这是一个布局组件包含侧边栏和 router-view children: [ { // 当访问 /dashboard 时默认渲染这个子路由 path: , name: dashboard.overview, component: DashboardOverview }, { // 访问 /dashboard/users 时UserList组件会渲染在DashboardLayout的router-view中 path: users, name: dashboard.users, component: UserList }, { path: settings, name: dashboard.settings, component: Settings } ] }在布局组件中使用router-view!-- DashboardLayout.vue -- template div classdashboard-layout Sidebar / div classmain-content !-- 子路由组件如DashboardOverview, UserList将在这里渲染 -- router-view / /div /div /template这样当访问/dashboard/users时DashboardLayout组件会被渲染同时它的router-view出口会渲染UserList组件共同构成完整的页面。命名视图 更复杂的情况一个路由需要同时渲染多个组件到不同的router-view出口。这时就需要命名视图。在路由配置中component要换成components复数并指定每个命名视图对应的组件。在模板中则使用router-view namexxx。{ path: /settings, components: { default: SettingsMain, // 默认的未命名的 router-view sidebar: SettingsSidebar, // 对应 router-view namesidebar footer: SettingsFooter // 对应 router-view namefooter } }template div router-view namesidebar/router-view router-view/router-view !-- 默认视图 -- router-view namefooter/router-view /div /template这种模式在需要高度定制化布局的场景下非常有用。4. 编程式导航与路由信息访问除了点击router-link很多时候我们需要在JavaScript逻辑中控制页面跳转比如表单提交成功后跳转到列表页。这就是编程式导航。4.1 使用router实例在组件模板中可以通过$router访问路由实例。在组合式API的setup函数中则需要通过useRouter这个组合式函数来获取。script setup import { useRouter } from vue-router const router useRouter() const goToAbout () { // 跳转到指定路径 router.push(/about) // 或使用命名的路由 router.push({ name: about }) // 带查询参数 router.push({ path: /search, query: { keyword: vue3 } }) // 替换当前历史记录而不是添加一条新记录用户点击后退不会回到当前页 router.replace({ name: home }) // 在历史记录中前进或后退 router.go(1) // 前进一页 router.go(-2) // 后退两页 router.back() // 等同于 go(-1) router.forward() // 等同于 go(1) } /scriptrouter.push是最常用的方法它会向历史栈添加一条新记录。router.replace则替换当前记录常用于登录后跳转等不希望用户返回登录页的场景。4.2 访问当前路由信息useRoute在组件内部我们经常需要获取当前路由的信息比如动态参数params、查询字符串query、哈希hash等。这需要通过useRoute组合式函数。script setup import { useRoute } from vue-router const route useRoute() // 假设路由定义为 { path: /user/:id/profile } // 当前URL是 /user/123/profile?namevue#section1 console.log(route.params) // { id: 123 } console.log(route.query) // { name: vue } console.log(route.hash) // #section1 console.log(route.fullPath) // /user/123/profile?namevue#section1 console.log(route.name) // 路由的名称 console.log(route.matched) // 匹配到的路由记录数组用于嵌套路由 /script一个关键细节route对象是一个响应式对象。这意味着你可以在模板中直接使用{{ route.params.id }}或者用watch监听它的变化。script setup import { useRoute, watch } from vue-router const route useRoute() // 监听路由参数id的变化当用户从 /user/1 切换到 /user/2 时重新获取用户数据 watch( () route.params.id, (newId) { if (newId) { fetchUserData(newId) } }, { immediate: true } // 组件创建时立即执行一次 ) /script注意事项 在Vue3的组合式API中useRoute和useRouter必须在setup函数或script setup的顶层作用域中调用。它们依赖于当前活跃的组件实例通过inject实现如果在异步回调或非同步的setup逻辑中调用可能会获取不到正确的实例。5. 高级路由特性与实战技巧掌握了基础我们来看看那些能让你的路由系统更强大、更健壮的高级特性。5.1 动态路由匹配与参数处理动态路由允许我们根据URL中的变量部分来渲染同一个组件。这在显示用户详情、文章内容等场景下非常普遍。定义与获取// router/index.js { path: /user/:id, // :id 是动态段 name: user, component: UserDetail }在UserDetail.vue组件中通过route.params.id即可获取到id的值。高级匹配模式 Vue Router使用path-to-regexp库作为路径匹配引擎支持很多高级模式。多段动态参数path: /user/:id/posts/:postId可选参数path: /user/:id?‘id可选匹配/user和/user/123匹配所有path: /files/:path(.*)*‘path参数会捕获/files/a/b/c中的a/b/c自定义正则path: /order/:id(\\d)‘只匹配数字ID参数变化响应 如前所述当从/user/1导航到/user/2时同一个组件实例会被复用。这意味着组件的生命周期钩子如mounted不会再次被调用。为了响应参数变化你有两种选择使用watch监听route.params如上文示例。使用onBeforeRouteUpdate导航守卫见下文。5.2 导航守卫路由的“安检系统”导航守卫是Vue Router最强大的功能之一它允许你在路由导航发生前、发生后进行拦截或执行一些操作。最常见的用途是权限验证、页面标题设置、数据预加载等。导航守卫分为三大类1. 全局守卫 作用于所有路由。router.beforeEach 在导航触发前调用。可以返回false取消导航返回一个路由路径/对象进行重定向或者不返回任何值或返回undefined/true让导航继续。// router/index.js router.beforeEach((to, from) { // to: 即将进入的目标路由 // from: 当前导航正要离开的路由 if (to.meta.requiresAuth !isUserLoggedIn()) { // 如果目标路由需要认证且用户未登录重定向到登录页 return { name: login, query: { redirect: to.fullPath } } } })router.afterEach 在导航完成后调用。适合用于分析、修改页面标题等不需要阻止导航的操作。router.afterEach((to, from) { document.title to.meta.title || My App // 发送页面浏览分析 sendToAnalytics(to.fullPath) })2. 路由独享守卫 在路由配置上直接定义的beforeEnter守卫只对该路由生效。javascript { path: /admin, component: AdminPanel, beforeEnter: (to, from) { // 仅检查/admin路由的权限 if (!userIsAdmin()) { return { name: forbidden } } } }3. 组件内守卫 在Vue组件内定义。onBeforeRouteUpdate 在当前路由改变但该组件被复用时调用例如动态参数变化。这是响应参数变化的最佳位置之一。script setup import { onBeforeRouteUpdate } from vue-router onBeforeRouteUpdate(async (to, from) { // 仅当id参数变化时重新获取数据 if (to.params.id ! from.params.id) { await fetchData(to.params.id) } }) /scriptonBeforeRouteLeave 在导航离开该组件的对应路由时调用。常用于防止用户在未保存表单时意外离开。script setup import { onBeforeRouteLeave } from vue-router const unsavedChanges ref(true) onBeforeRouteLeave((to, from) { if (unsavedChanges.value) { const answer window.confirm(有未保存的更改确定要离开吗) if (!answer) { return false // 取消导航 } } }) /script实操心得 导航守卫的执行顺序是onBeforeRouteLeave组件 -beforeEach全局 -beforeEnter路由 -onBeforeRouteUpdate组件如果复用 -afterEach全局。理解这个顺序对于调试复杂的守卫逻辑至关重要。另外守卫函数可以是异步的asyncVue Router会等待它们解析完成。5.3 路由元信息与滚动行为路由元信息 (meta) 你可以在定义路由时附加一个meta对象用来存放任何与路由相关的信息然后在守卫或组件中访问route.meta。这是实现权限控制、面包屑导航、页面标题等的通用模式。{ path: /dashboard, component: Dashboard, meta: { requiresAuth: true, title: 控制面板, breadcrumb: 首页 } }滚动行为 在单页面应用中当用户通过浏览器的前进/后退按钮导航时Vue Router可以模拟原生浏览器行为让页面滚动到之前的位置。你可以在创建路由实例时配置scrollBehavior函数。const router createRouter({ history: createWebHistory(), routes, scrollBehavior(to, from, savedPosition) { // 如果前进/后退有保存的位置则滚动到该位置 if (savedPosition) { return savedPosition } // 否则滚动到页面顶部 return { top: 0 } // 也可以滚动到指定元素 // return { el: #main, top: -20 } } })6. 常见问题排查与性能优化实战在实际开发中你一定会遇到各种路由相关的问题。这里我总结了一些高频问题和优化技巧。6.1 路由缓存失效与组件复用问题问题描述 在使用router-view配合keep-alive缓存组件时或者期望组件在参数变化时复用以提升性能时发现组件没有按预期工作例如mounted重复触发、数据不更新。根因分析 Vue Router的核心机制是组件复用。当路由匹配到同一个组件且路径参数params或查询参数query发生变化时默认会复用组件实例而不是销毁再创建。这提升了性能但也意味着mounted等生命周期钩子不会再次执行。解决方案使用key属性强制替换 给router-view或被缓存的组件添加一个唯一的key可以强制Vue在每次路由变化时重新创建组件。router-view :keyroute.fullPath / !-- 或者 -- keep-alive component :isComponent :keyroute.fullPath / /keep-alive优点简单粗暴总能保证组件刷新。缺点破坏了组件复用带来的性能优势可能导致状态丢失如表单输入。使用watch或onBeforeRouteUpdate守卫响应变化 这是更推荐的做法。在组件内部监听路由参数的变化并手动执行数据获取等副作用。script setup import { watch, ref } from vue import { useRoute } from vue-router const route useRoute() const userData ref(null) const fetchUser async (id) { userData.value await api.getUser(id) } // 方案A使用watch watch( () route.params.id, (newId) { if (newId) fetchUser(newId) }, { immediate: true } ) // 方案B使用onBeforeRouteUpdate守卫更适合组合式API import { onBeforeRouteUpdate } from vue-router onBeforeRouteUpdate(async (to) { await fetchUser(to.params.id) }) /script优点保持了组件复用性能好。缺点需要手动管理数据获取逻辑。6.2 路由懒加载与代码分割最佳实践懒加载是提升大型应用初始加载速度的关键。Vite和Webpack都支持动态导入import()语法来实现代码分割。基础懒加载component: () import(./views/HeavyComponent.vue)分组/预加载 你可以使用Webpack的魔法注释或Vite的/* webpackChunkName: group-name */Vite也支持来将多个组件打包到同一个异步块中或者预加载某些关键路由。// Vite/Webpack中将多个路由组件打包到同一个chunk component: () import(/* webpackChunkName: group-user */ ./views/UserDetail.vue) // 另一个路由也使用相同的chunk名 component: () import(/* webpackChunkName: group-user */ ./views/UserEdit.vue)预加载策略 你可以在用户可能访问的下一个页面进行预加载。Vue Router 4提供了router.isReady()方法和路由守卫可以在主路由解析完成后在后台预加载其他路由。// 在主应用挂载后预加载某些关键路由 app.use(router) router.isReady().then(() { // 预加载关于页 import(./views/AboutView.vue) }) app.mount(#app)6.3 动态路由与权限管理集成对于后台管理系统菜单和路由权限通常是动态的由用户角色决定。这需要实现动态添加路由。核心APIrouter.addRoute() Vue Router 4允许你在运行时动态添加路由规则。典型流程前端定义所有可能的路由包括需要权限和公共路由但初始化时只注册公共路由如登录页、404页。用户登录成功后后端返回该用户有权限访问的路由菜单列表。前端根据这个列表筛选出对应的路由配置对象然后通过router.addRoute()逐个或批量添加到路由实例中。动态添加的路由可以立即访问。// 1. 初始路由只包含公共部分 const publicRoutes [ { path: /login, component: Login }, { path: /404, component: NotFound } ] const router createRouter({ history, routes: publicRoutes }) // 2. 登录后获取用户权限路由 async function initUserRoutes(userRole) { const asyncRoutes await fetchRoutesByRole(userRole) // 从API获取 // 3. 动态添加 asyncRoutes.forEach(route { // 注意addRoute可以添加顶级路由也可以为现有路由添加子路由 // router.addRoute(route) // 添加为顶级路由 // 或者添加到某个父路由下 router.addRoute(admin, route) // 假设admin是一个已存在的路由名称 }) // 4. 可选添加一个兜底的404路由必须放在最后 router.addRoute({ path: /:pathMatch(.*)*, name: NotFound, component: NotFound }) }重要提示 动态添加路由后原有的路由匹配可能失效。一个常见的做法是在动态添加完所有权限路由后最后再添加一个通配符404路由以确保任何未匹配的路径都能被捕获。另外动态路由的变化不是响应式的如果你需要基于路由生成菜单可能需要使用router.getRoutes()来获取当前所有路由记录。6.4 部署History模式的服务端配置如果你使用HTML5 History模式createWebHistory在开发环境下一切正常但部署到生产服务器后一刷新页面就出现404错误。问题原因 当你在浏览器中直接访问https://example.com/user/123或刷新该页面时这个请求会发送到你的服务器。服务器需要能识别这个URL并返回你的单页面应用的主入口文件通常是index.html然后由前端的Vue Router来解析路由并渲染对应组件。如果服务器没有配置它会去文件系统里找/user/123这个文件或目录显然找不到于是返回404。解决方案 你需要配置你的生产服务器将所有非静态文件如图片、CSS、JS的请求都重定向到index.html。Nginx 配置示例location / { try_files $uri $uri/ /index.html; }Apache 配置示例在.htaccess文件中RewriteEngine On RewriteBase / RewriteRule ^index\.html$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.html [L]Vercel / Netlify 等静态托管平台 通常只需在根目录放置一个_redirects或vercel.json/netlify.toml文件进行类似配置即可很多Vue脚手架生成的项目已经包含了。确保在部署前处理好这个配置否则History模式的路由将无法正常工作。7. 与状态管理Pinia及第三方库的集成在真实项目中路由很少孤立存在它经常需要和状态管理、UI库等协同工作。7.1 在Pinia Store中使用路由在Pinia Store中你无法直接使用useRouter或useRoute因为它们依赖于组件实例。你需要在组件中调用这些函数然后将路由实例或信息传递给Store的Action或者更优雅地在Store内部获取当前活跃的路由。一种常见模式是在Store Action中接收路由参数// stores/userStore.js import { defineStore } from pinia export const useUserStore defineStore(user, { actions: { async fetchUser(userId) { this.user await api.fetchUser(userId) } } })!-- UserDetail.vue -- script setup import { useRoute } from vue-router import { useUserStore } from /stores/user const route useRoute() const userStore useUserStore() // 在组件中调用store action并传入路由参数 userStore.fetchUser(route.params.id) /script如果你确实需要在Store内部访问路由例如在一个复杂的、与路由深度绑定的全局逻辑中可以考虑将router实例作为参数传递给Store的构造函数或者使用一个提供全局服务的Store来封装路由相关逻辑但这通常增加了耦合度需谨慎使用。7.2 与UI库如Element Plus的集成像Element Plus这样的UI库其导航菜单el-menu组件通常需要与路由状态同步高亮当前项。这可以通过将菜单的index属性绑定到当前路由的路径或名称来实现。template el-menu :default-activeactiveMenu router selecthandleSelect el-menu-item index/dashboard template #title控制台/template /el-menu-item el-menu-item index/user/list template #title用户管理/template /el-menu-item /el-menu /template script setup import { computed } from vue import { useRoute } from vue-router const route useRoute() // 计算当前激活的菜单项通常取路由的path或一个meta中定义的key const activeMenu computed(() route.path) const handleSelect (index) { // 因为设置了 router 属性el-menu会自动调用 router.push(index) // 这里可以处理一些额外的逻辑 console.log(导航到:, index) } /script设置el-menu的router属性为true后点击菜单项会自动调用router.push进行导航非常方便。你只需要确保index的值与路由的path或name匹配即可。路由管理是现代前端应用架构的基石。从简单的页面跳转到复杂的权限控制、数据流管理Vue Router提供了一整套成熟的解决方案。在Vue3的组合式API范式下通过useRouter和useRoute来访问路由相关功能让代码更加清晰和可组合。记住几个关键点多用命名路由、善用导航守卫处理权限和副作用、理解组件复用机制并合理使用watch或onBeforeRouteUpdate响应变化、部署History模式别忘了服务器配置。把这些点吃透你就能驾驭绝大多数Vue3项目中的路由需求了。在实际开发中结合Pinia管理全局状态再搭配UI库的导航组件你就能搭建出既健壮又用户体验良好的前端应用。
Vue Router 4 从入门到实战：Vue3 路由管理与SPA开发指南
发布时间：2026/7/31 11:49:51
1. 项目概述为什么Vue Router是Vue3项目的“导航大脑”如果你正在用Vue3开发一个稍微复杂点的应用比如一个后台管理系统或者一个内容网站你很快就会遇到一个核心问题如何管理页面用户点击一个菜单怎么切换到对应的组件浏览器的前进后退按钮怎么让它正常工作页面之间怎么传递参数这些看似基础的需求背后都需要一个专门的路由系统来支撑。Vue Router就是Vue生态中专为这个任务而生的官方路由库。在Vue3的时代它也跟着升级到了Vue Router 4虽然核心概念没变但在组合式APIComposition API的支持、TypeScript集成以及一些API设计上有了更现代化、更贴合Vue3开发习惯的用法。简单来说你可以把Vue Router理解为应用的“导航大脑”。它负责监听URL的变化根据你预先定义好的规则路由表找到对应的Vue组件并将其渲染到指定的位置通常是router-view。没有它你的单页面应用SPA就只是一堆静态组件的堆砌无法实现真正的页面跳转和状态管理。对于新手理解并掌握Vue Router是迈向Vue3实战开发的关键一步对于有Vue2经验的开发者了解Vue Router 4的变化则是平滑过渡的必修课。接下来我会以一个典型的后台管理系统为场景带你从零开始深入每一个细节把Vue Router在Vue3中的使用讲透。2. 环境搭建与基础配置从零创建一个带路由的Vue3项目2.1 项目初始化与Vue Router安装现在创建Vue3项目Vite是绝对的主流选择它速度快、配置简单。我们从头开始创建一个集成了Vue Router的项目。打开你的终端执行以下命令# 使用 npm 7 的额外双横线 npm create vuelatest my-vue-router-app # 或者使用 yarn yarn create vue my-vue-router-app # 或者使用 pnpm pnpm create vue my-vue-router-app这个命令会启动一个交互式的项目创建向导。你会被询问一系列问题这里是我们需要关注的选项Add TypeScript? 根据需求选择本文示例使用JavaScript。Add JSX Support? 选择No除非你明确需要使用JSX。Add Vue Router for Single Page Application development?务必选择 Yes。这是最关键的一步它会自动为我们安装vue-router包并生成基础的路由配置。Add Pinia for state management? 可选状态管理不是本文重点。Add Vitest for Unit Testing? 可选。Add an End-to-End Testing Solution? 可选。Add ESLint for code quality? 建议选择Yes保持代码规范。一路选择完毕后进入项目目录并安装依赖cd my-vue-router-app npm install # 或 yarn / pnpm install注意 如果你在一个已有的、没有安装Vue Router的Vue3项目中手动安装可以使用npm install vue-router4。但强烈推荐使用上述create vue脚手架它能生成最标准、最省心的初始配置。安装完成后观察项目结构你会发现多了一个src/router目录里面有一个index.js或index.ts文件。这就是我们路由系统的核心配置文件。2.2 路由配置文件深度解析让我们打开src/router/index.js看看脚手架为我们生成了什么import { createRouter, createWebHistory } from vue-router import HomeView from ../views/HomeView.vue const router createRouter({ // 1. 使用 HTML5 History 模式 history: createWebHistory(import.meta.env.BASE_URL), // 2. 定义路由表 routes: [ { path: /, name: home, component: HomeView }, { path: /about, name: about, // 路由级代码分割懒加载组件 component: () import(../views/AboutView.vue) } ] }) export default router我们来逐行拆解这个配置的核心createRouter 这是Vue Router 4的工厂函数用于创建路由实例。它接收一个配置对象。history模式createWebHistory()创建的是HTML5 History模式。它利用history.pushStateAPI让URL看起来像正常的路径如/about而不是带#的哈希模式如/#/about。这更美观对SEO也更友好。import.meta.env.BASE_URL是Vite提供的环境变量如果你的应用部署在子路径如https://example.com/my-app/它会自动处理基础路径。对比哈希模式 你可以使用createWebHashHistory()来启用哈希模式。它的优点是兼容性极好无需服务器额外配置。但URL中的#不太美观。对于现代浏览器History模式是首选。routes数组 这是路由表一个对象数组。每个对象定义一条路由规则。path 匹配的URL路径。可以是静态字符串/about也可以是动态段/user/:id。name 路由的唯一名称。在编程式导航或router-link中可以通过名称来引用路由这比硬编码路径更可靠尤其是在路径结构可能改变时。component 该路径下要渲染的组件。这里展示了两种方式直接导入component: HomeView。适用于核心、首屏必须的组件。懒加载推荐component: () import(../views/AboutView.vue)。这是通过动态导入实现的代码分割。当用户访问/about路径时才会加载AboutView.vue这个组件的代码。这能显著提升应用初始加载速度是构建大型应用的必备优化手段。这个路由实例创建后需要在主应用入口通常是src/main.js中被挂载到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)至此一个具备基本路由功能的Vue3应用就搭建好了。运行npm run dev你就能在页面中通过导航栏点击在Home和About页面间切换。3. 核心概念与组件实战router-link与router-view路由配置好了怎么在页面上用呢主要靠两个内置组件。3.1router-link声明式导航的利器在src/App.vue中你会看到类似这样的导航代码template nav router-link to/Home/router-link | router-link to/aboutAbout/router-link /nav router-view/ /templaterouter-link是用于替代原生a标签进行导航的组件。它的核心优势在于在单页面应用内部进行跳转不会触发浏览器整页刷新体验流畅。自动获取激活状态。当链接指向的路由被激活时组件会自动添加一个router-link-active的CSS类默认行为可配置方便你为当前选中的导航项设置高亮样式。router-link的to属性非常灵活路径字符串to/about带有路径的对象to{ path: /about }带有命名的路由对象更推荐to{ name: about }。这样做的好处是即使你后来修改了/about这个路径只要name不变所有引用它的链接都无需更改。带查询参数和哈希to{ path: /search, query: { q: vue }, hash: #results }实操心得 在大型项目中我强烈建议始终使用name进行导航。路径可能会因为业务调整而改变例如从/user改为/member但路由名称通常是业务逻辑的抽象如userProfile更稳定。这能极大减少因路径变更导致的链接失效问题。3.2router-view路由组件的渲染出口router-view是一个功能性组件它就像一个“占位符”或“窗口”。路由匹配到的组件将会被渲染在router-view所在的位置。你可以把它理解为一个动态的组件交换机。嵌套路由与多个router-view 这是Vue Router进阶使用的关键。一个复杂的应用界面通常是嵌套的。例如一个后台管理系统顶部有导航栏左侧有菜单栏中间是主要内容区。这就可以通过嵌套路由来实现。定义嵌套路由 在路由配置中通过children属性来定义子路由。// router/index.js { path: /dashboard, name: dashboard, component: DashboardLayout, // 这是一个布局组件包含侧边栏和 router-view children: [ { // 当访问 /dashboard 时默认渲染这个子路由 path: , name: dashboard.overview, component: DashboardOverview }, { // 访问 /dashboard/users 时UserList组件会渲染在DashboardLayout的router-view中 path: users, name: dashboard.users, component: UserList }, { path: settings, name: dashboard.settings, component: Settings } ] }在布局组件中使用router-view!-- DashboardLayout.vue -- template div classdashboard-layout Sidebar / div classmain-content !-- 子路由组件如DashboardOverview, UserList将在这里渲染 -- router-view / /div /div /template这样当访问/dashboard/users时DashboardLayout组件会被渲染同时它的router-view出口会渲染UserList组件共同构成完整的页面。命名视图 更复杂的情况一个路由需要同时渲染多个组件到不同的router-view出口。这时就需要命名视图。在路由配置中component要换成components复数并指定每个命名视图对应的组件。在模板中则使用router-view namexxx。{ path: /settings, components: { default: SettingsMain, // 默认的未命名的 router-view sidebar: SettingsSidebar, // 对应 router-view namesidebar footer: SettingsFooter // 对应 router-view namefooter } }template div router-view namesidebar/router-view router-view/router-view !-- 默认视图 -- router-view namefooter/router-view /div /template这种模式在需要高度定制化布局的场景下非常有用。4. 编程式导航与路由信息访问除了点击router-link很多时候我们需要在JavaScript逻辑中控制页面跳转比如表单提交成功后跳转到列表页。这就是编程式导航。4.1 使用router实例在组件模板中可以通过$router访问路由实例。在组合式API的setup函数中则需要通过useRouter这个组合式函数来获取。script setup import { useRouter } from vue-router const router useRouter() const goToAbout () { // 跳转到指定路径 router.push(/about) // 或使用命名的路由 router.push({ name: about }) // 带查询参数 router.push({ path: /search, query: { keyword: vue3 } }) // 替换当前历史记录而不是添加一条新记录用户点击后退不会回到当前页 router.replace({ name: home }) // 在历史记录中前进或后退 router.go(1) // 前进一页 router.go(-2) // 后退两页 router.back() // 等同于 go(-1) router.forward() // 等同于 go(1) } /scriptrouter.push是最常用的方法它会向历史栈添加一条新记录。router.replace则替换当前记录常用于登录后跳转等不希望用户返回登录页的场景。4.2 访问当前路由信息useRoute在组件内部我们经常需要获取当前路由的信息比如动态参数params、查询字符串query、哈希hash等。这需要通过useRoute组合式函数。script setup import { useRoute } from vue-router const route useRoute() // 假设路由定义为 { path: /user/:id/profile } // 当前URL是 /user/123/profile?namevue#section1 console.log(route.params) // { id: 123 } console.log(route.query) // { name: vue } console.log(route.hash) // #section1 console.log(route.fullPath) // /user/123/profile?namevue#section1 console.log(route.name) // 路由的名称 console.log(route.matched) // 匹配到的路由记录数组用于嵌套路由 /script一个关键细节route对象是一个响应式对象。这意味着你可以在模板中直接使用{{ route.params.id }}或者用watch监听它的变化。script setup import { useRoute, watch } from vue-router const route useRoute() // 监听路由参数id的变化当用户从 /user/1 切换到 /user/2 时重新获取用户数据 watch( () route.params.id, (newId) { if (newId) { fetchUserData(newId) } }, { immediate: true } // 组件创建时立即执行一次 ) /script注意事项 在Vue3的组合式API中useRoute和useRouter必须在setup函数或script setup的顶层作用域中调用。它们依赖于当前活跃的组件实例通过inject实现如果在异步回调或非同步的setup逻辑中调用可能会获取不到正确的实例。5. 高级路由特性与实战技巧掌握了基础我们来看看那些能让你的路由系统更强大、更健壮的高级特性。5.1 动态路由匹配与参数处理动态路由允许我们根据URL中的变量部分来渲染同一个组件。这在显示用户详情、文章内容等场景下非常普遍。定义与获取// router/index.js { path: /user/:id, // :id 是动态段 name: user, component: UserDetail }在UserDetail.vue组件中通过route.params.id即可获取到id的值。高级匹配模式 Vue Router使用path-to-regexp库作为路径匹配引擎支持很多高级模式。多段动态参数path: /user/:id/posts/:postId可选参数path: /user/:id?‘id可选匹配/user和/user/123匹配所有path: /files/:path(.*)*‘path参数会捕获/files/a/b/c中的a/b/c自定义正则path: /order/:id(\\d)‘只匹配数字ID参数变化响应 如前所述当从/user/1导航到/user/2时同一个组件实例会被复用。这意味着组件的生命周期钩子如mounted不会再次被调用。为了响应参数变化你有两种选择使用watch监听route.params如上文示例。使用onBeforeRouteUpdate导航守卫见下文。5.2 导航守卫路由的“安检系统”导航守卫是Vue Router最强大的功能之一它允许你在路由导航发生前、发生后进行拦截或执行一些操作。最常见的用途是权限验证、页面标题设置、数据预加载等。导航守卫分为三大类1. 全局守卫 作用于所有路由。router.beforeEach 在导航触发前调用。可以返回false取消导航返回一个路由路径/对象进行重定向或者不返回任何值或返回undefined/true让导航继续。// router/index.js router.beforeEach((to, from) { // to: 即将进入的目标路由 // from: 当前导航正要离开的路由 if (to.meta.requiresAuth !isUserLoggedIn()) { // 如果目标路由需要认证且用户未登录重定向到登录页 return { name: login, query: { redirect: to.fullPath } } } })router.afterEach 在导航完成后调用。适合用于分析、修改页面标题等不需要阻止导航的操作。router.afterEach((to, from) { document.title to.meta.title || My App // 发送页面浏览分析 sendToAnalytics(to.fullPath) })2. 路由独享守卫 在路由配置上直接定义的beforeEnter守卫只对该路由生效。javascript { path: /admin, component: AdminPanel, beforeEnter: (to, from) { // 仅检查/admin路由的权限 if (!userIsAdmin()) { return { name: forbidden } } } }3. 组件内守卫 在Vue组件内定义。onBeforeRouteUpdate 在当前路由改变但该组件被复用时调用例如动态参数变化。这是响应参数变化的最佳位置之一。script setup import { onBeforeRouteUpdate } from vue-router onBeforeRouteUpdate(async (to, from) { // 仅当id参数变化时重新获取数据 if (to.params.id ! from.params.id) { await fetchData(to.params.id) } }) /scriptonBeforeRouteLeave 在导航离开该组件的对应路由时调用。常用于防止用户在未保存表单时意外离开。script setup import { onBeforeRouteLeave } from vue-router const unsavedChanges ref(true) onBeforeRouteLeave((to, from) { if (unsavedChanges.value) { const answer window.confirm(有未保存的更改确定要离开吗) if (!answer) { return false // 取消导航 } } }) /script实操心得 导航守卫的执行顺序是onBeforeRouteLeave组件 -beforeEach全局 -beforeEnter路由 -onBeforeRouteUpdate组件如果复用 -afterEach全局。理解这个顺序对于调试复杂的守卫逻辑至关重要。另外守卫函数可以是异步的asyncVue Router会等待它们解析完成。5.3 路由元信息与滚动行为路由元信息 (meta) 你可以在定义路由时附加一个meta对象用来存放任何与路由相关的信息然后在守卫或组件中访问route.meta。这是实现权限控制、面包屑导航、页面标题等的通用模式。{ path: /dashboard, component: Dashboard, meta: { requiresAuth: true, title: 控制面板, breadcrumb: 首页 } }滚动行为 在单页面应用中当用户通过浏览器的前进/后退按钮导航时Vue Router可以模拟原生浏览器行为让页面滚动到之前的位置。你可以在创建路由实例时配置scrollBehavior函数。const router createRouter({ history: createWebHistory(), routes, scrollBehavior(to, from, savedPosition) { // 如果前进/后退有保存的位置则滚动到该位置 if (savedPosition) { return savedPosition } // 否则滚动到页面顶部 return { top: 0 } // 也可以滚动到指定元素 // return { el: #main, top: -20 } } })6. 常见问题排查与性能优化实战在实际开发中你一定会遇到各种路由相关的问题。这里我总结了一些高频问题和优化技巧。6.1 路由缓存失效与组件复用问题问题描述 在使用router-view配合keep-alive缓存组件时或者期望组件在参数变化时复用以提升性能时发现组件没有按预期工作例如mounted重复触发、数据不更新。根因分析 Vue Router的核心机制是组件复用。当路由匹配到同一个组件且路径参数params或查询参数query发生变化时默认会复用组件实例而不是销毁再创建。这提升了性能但也意味着mounted等生命周期钩子不会再次执行。解决方案使用key属性强制替换 给router-view或被缓存的组件添加一个唯一的key可以强制Vue在每次路由变化时重新创建组件。router-view :keyroute.fullPath / !-- 或者 -- keep-alive component :isComponent :keyroute.fullPath / /keep-alive优点简单粗暴总能保证组件刷新。缺点破坏了组件复用带来的性能优势可能导致状态丢失如表单输入。使用watch或onBeforeRouteUpdate守卫响应变化 这是更推荐的做法。在组件内部监听路由参数的变化并手动执行数据获取等副作用。script setup import { watch, ref } from vue import { useRoute } from vue-router const route useRoute() const userData ref(null) const fetchUser async (id) { userData.value await api.getUser(id) } // 方案A使用watch watch( () route.params.id, (newId) { if (newId) fetchUser(newId) }, { immediate: true } ) // 方案B使用onBeforeRouteUpdate守卫更适合组合式API import { onBeforeRouteUpdate } from vue-router onBeforeRouteUpdate(async (to) { await fetchUser(to.params.id) }) /script优点保持了组件复用性能好。缺点需要手动管理数据获取逻辑。6.2 路由懒加载与代码分割最佳实践懒加载是提升大型应用初始加载速度的关键。Vite和Webpack都支持动态导入import()语法来实现代码分割。基础懒加载component: () import(./views/HeavyComponent.vue)分组/预加载 你可以使用Webpack的魔法注释或Vite的/* webpackChunkName: group-name */Vite也支持来将多个组件打包到同一个异步块中或者预加载某些关键路由。// Vite/Webpack中将多个路由组件打包到同一个chunk component: () import(/* webpackChunkName: group-user */ ./views/UserDetail.vue) // 另一个路由也使用相同的chunk名 component: () import(/* webpackChunkName: group-user */ ./views/UserEdit.vue)预加载策略 你可以在用户可能访问的下一个页面进行预加载。Vue Router 4提供了router.isReady()方法和路由守卫可以在主路由解析完成后在后台预加载其他路由。// 在主应用挂载后预加载某些关键路由 app.use(router) router.isReady().then(() { // 预加载关于页 import(./views/AboutView.vue) }) app.mount(#app)6.3 动态路由与权限管理集成对于后台管理系统菜单和路由权限通常是动态的由用户角色决定。这需要实现动态添加路由。核心APIrouter.addRoute() Vue Router 4允许你在运行时动态添加路由规则。典型流程前端定义所有可能的路由包括需要权限和公共路由但初始化时只注册公共路由如登录页、404页。用户登录成功后后端返回该用户有权限访问的路由菜单列表。前端根据这个列表筛选出对应的路由配置对象然后通过router.addRoute()逐个或批量添加到路由实例中。动态添加的路由可以立即访问。// 1. 初始路由只包含公共部分 const publicRoutes [ { path: /login, component: Login }, { path: /404, component: NotFound } ] const router createRouter({ history, routes: publicRoutes }) // 2. 登录后获取用户权限路由 async function initUserRoutes(userRole) { const asyncRoutes await fetchRoutesByRole(userRole) // 从API获取 // 3. 动态添加 asyncRoutes.forEach(route { // 注意addRoute可以添加顶级路由也可以为现有路由添加子路由 // router.addRoute(route) // 添加为顶级路由 // 或者添加到某个父路由下 router.addRoute(admin, route) // 假设admin是一个已存在的路由名称 }) // 4. 可选添加一个兜底的404路由必须放在最后 router.addRoute({ path: /:pathMatch(.*)*, name: NotFound, component: NotFound }) }重要提示 动态添加路由后原有的路由匹配可能失效。一个常见的做法是在动态添加完所有权限路由后最后再添加一个通配符404路由以确保任何未匹配的路径都能被捕获。另外动态路由的变化不是响应式的如果你需要基于路由生成菜单可能需要使用router.getRoutes()来获取当前所有路由记录。6.4 部署History模式的服务端配置如果你使用HTML5 History模式createWebHistory在开发环境下一切正常但部署到生产服务器后一刷新页面就出现404错误。问题原因 当你在浏览器中直接访问https://example.com/user/123或刷新该页面时这个请求会发送到你的服务器。服务器需要能识别这个URL并返回你的单页面应用的主入口文件通常是index.html然后由前端的Vue Router来解析路由并渲染对应组件。如果服务器没有配置它会去文件系统里找/user/123这个文件或目录显然找不到于是返回404。解决方案 你需要配置你的生产服务器将所有非静态文件如图片、CSS、JS的请求都重定向到index.html。Nginx 配置示例location / { try_files $uri $uri/ /index.html; }Apache 配置示例在.htaccess文件中RewriteEngine On RewriteBase / RewriteRule ^index\.html$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.html [L]Vercel / Netlify 等静态托管平台 通常只需在根目录放置一个_redirects或vercel.json/netlify.toml文件进行类似配置即可很多Vue脚手架生成的项目已经包含了。确保在部署前处理好这个配置否则History模式的路由将无法正常工作。7. 与状态管理Pinia及第三方库的集成在真实项目中路由很少孤立存在它经常需要和状态管理、UI库等协同工作。7.1 在Pinia Store中使用路由在Pinia Store中你无法直接使用useRouter或useRoute因为它们依赖于组件实例。你需要在组件中调用这些函数然后将路由实例或信息传递给Store的Action或者更优雅地在Store内部获取当前活跃的路由。一种常见模式是在Store Action中接收路由参数// stores/userStore.js import { defineStore } from pinia export const useUserStore defineStore(user, { actions: { async fetchUser(userId) { this.user await api.fetchUser(userId) } } })!-- UserDetail.vue -- script setup import { useRoute } from vue-router import { useUserStore } from /stores/user const route useRoute() const userStore useUserStore() // 在组件中调用store action并传入路由参数 userStore.fetchUser(route.params.id) /script如果你确实需要在Store内部访问路由例如在一个复杂的、与路由深度绑定的全局逻辑中可以考虑将router实例作为参数传递给Store的构造函数或者使用一个提供全局服务的Store来封装路由相关逻辑但这通常增加了耦合度需谨慎使用。7.2 与UI库如Element Plus的集成像Element Plus这样的UI库其导航菜单el-menu组件通常需要与路由状态同步高亮当前项。这可以通过将菜单的index属性绑定到当前路由的路径或名称来实现。template el-menu :default-activeactiveMenu router selecthandleSelect el-menu-item index/dashboard template #title控制台/template /el-menu-item el-menu-item index/user/list template #title用户管理/template /el-menu-item /el-menu /template script setup import { computed } from vue import { useRoute } from vue-router const route useRoute() // 计算当前激活的菜单项通常取路由的path或一个meta中定义的key const activeMenu computed(() route.path) const handleSelect (index) { // 因为设置了 router 属性el-menu会自动调用 router.push(index) // 这里可以处理一些额外的逻辑 console.log(导航到:, index) } /script设置el-menu的router属性为true后点击菜单项会自动调用router.push进行导航非常方便。你只需要确保index的值与路由的path或name匹配即可。路由管理是现代前端应用架构的基石。从简单的页面跳转到复杂的权限控制、数据流管理Vue Router提供了一整套成熟的解决方案。在Vue3的组合式API范式下通过useRouter和useRoute来访问路由相关功能让代码更加清晰和可组合。记住几个关键点多用命名路由、善用导航守卫处理权限和副作用、理解组件复用机制并合理使用watch或onBeforeRouteUpdate响应变化、部署History模式别忘了服务器配置。把这些点吃透你就能驾驭绝大多数Vue3项目中的路由需求了。在实际开发中结合Pinia管理全局状态再搭配UI库的导航组件你就能搭建出既健壮又用户体验良好的前端应用。
