做 Vue 开发绕不开的就是路由配置。我在项目中不管接手的是后台管理系统还是 H5 活动页第一件事永远是打开路由配置文件从上往下扫一遍。路由配置写得好不好直接决定后续加页面、加权限、做埋点时是“改一行配置就行”还是“到处打补丁”。这篇文章我就把 Vue 3 Vue Router 4 的路由配置完整拆开讲一遍从基础的路由表设计到嵌套路由、动态路由、路由守卫、懒加载再到我实际开发中踩过的坑和排查方法尽量写成可以直接照抄的经验文档。不管你是刚学 Vue 还没搞明白routes数组里每一行是什么意思的新手还是已经在项目里写过路由但遇到刷新 404、重复跳转报错、动态加路由白屏这些怪问题的开发者这篇文章应该都能对你有用。1. 路由配置的核心思路拆解1.1 路由到底在解决什么问题先说个最简单的场景。传统多页面开发时浏览器地址栏从/index.html切到/about.html实际上是向服务器发起两次请求服务器返回两个不同的 HTML 文件。SPA 单页应用只有一个index.html你要从首页切到关于页不能再请求服务器了只能由前端 JavaScript 自己根据地址栏的变化动态替换页面上的内容组件。这个时候就需要一个“地址映射规则表”也就是路由配置。Vue Router 做的事就是把“URL 路径”和“组件”绑定起来路径是/home就渲染 Home 组件路径是/user/profile就渲染 UserProfile 组件。它还额外处理了浏览器的前进后退、页面刷新时的状态恢复、路由切换过程中的拦截逻辑等。理解这个本质再看路由配置里的每一项参数就不会觉得是在死记配置 API而是在真的设计一张映射表。1.2 路由模式选择History 与 Hash 各自的取舍Vue Router 4 创建路由实例时最常见的两个模式是createWebHistory和createWebHashHistory。import { createRouter, createWebHistory } from vue-router const router createRouter({ history: createWebHistory(), routes: [] })createWebHistory模式生成的 URL 长这样https://example.com/user/profile地址栏干净清爽也是我在项目中的默认选择。但它有一个前提条件后端服务器必须把所有非文件资源的请求都重定向到index.html。因为用户访问/user/profile时服务器上并不存在这个物理路径如果你不做重定向用户一刷新页面浏览器拿到的就是 404。生产环境中这个配置通常在 Nginx 里处理常见写法是location / { try_files $uri $uri/ /index.html; }createWebHashHistory模式的 URL 是https://example.com/#/user/profile#后面的内容不会发送到服务器所以刷新页面不会有 404 问题。缺点是地址栏不好看且#之后的路径变化在某些业务场景下做埋点、做分享链接会麻烦一些。我的建议很简单能保证后端配合就优先用 History 模式图省事或者后端不好改就用 Hash 模式。两种模式只是路由实例的入参不同后面的routes数组配置完全一致后续想切换成本很低。1.3 路由配置文件的组织方式项目小的时候所有路由写在一个router/index.js里还能接受。项目一旦超过几十个页面全堆在一起就非常痛苦每次看路由表要滚动很久。我习惯把路由表按业务模块拆成独立文件再用main.ts统一整合。比如一个电商项目可以拆出user.ts、order.ts、product.ts三个模块路由文件// router/modules/user.ts export default [ { path: /user, component: () import(/layouts/UserLayout.vue), children: [ { path: , redirect: /user/profile }, { path: profile, component: () import(/views/user/Profile.vue) }, { path: address, component: () import(/views/user/Address.vue) } ] } ]// router/index.ts import { createRouter, createWebHistory } from vue-router import userRoutes from ./modules/user import orderRoutes from ./modules/order import productRoutes from ./modules/product const router createRouter({ history: createWebHistory(), routes: [ { path: /, redirect: /home }, { path: /home, component: () import(/views/Home.vue) }, ...userRoutes, ...orderRoutes, ...productRoutes ] })这种写法有几个好处第一不同业务线的路由由对应负责人维护Git 冲突明显减少。第二路由配置和业务目录结构能保持同步。第三后续如果要按模块做权限控制也可以直接把某个模块的路由整体加到权限配置里。2. routes 数组配置项详解routes数组是路由配置的核心数组里的每一项都是一个路由记录对象。我在 code review 时发现很多新人会把每条路由都写成一样的模板不太清楚某些字段到底在什么场景用。下面按我实际使用的频率来逐个说。2.1 最常用的基础配置项一个最典型的配置项组合是{ path: /product/detail/:id, name: ProductDetail, component: () import(/views/product/Detail.vue), meta: { title: 商品详情, requiresAuth: true } }path是路径支持静态路径和动态参数动态参数用冒号声明比如:id。name是路由名称后续跳转用router.push({ name: ProductDetail, params: { id: 1 } })时会比直接拼路径字符串更安全——路径变了路由名不变代码就不用改。meta是一个只做信息承载的对象官方称之为“路由元信息”。我习惯把页面标题、是否需要登录、页面权限标识、埋点编号等非路由逻辑的数据都放进去。页面标题可以在全局守卫里读取权限标识则可以配合登录状态做拦截判断。这里有一个容易踩的细节name必须是全局唯一的不能两个路由记录用同一个name。否则 Vue Router 会报一条警告并且跳转时会拿到最先匹配的那个记录行为会变得非常诡异。2.2 嵌套路由与子路由配置后台管理系统几乎必用嵌套路由。原因在于后台页面通常有一个统一的侧边栏和顶部栏骨架只有中间内容区随路由变化。如果你不做嵌套路由侧边栏的展示逻辑就要在每个页面组件里写一遍非常臃肿。嵌套路由的写法是在父路由上加children{ path: /shop, component: () import(/layouts/ShopLayout.vue), redirect: /shop/goods, children: [ { path: goods, component: () import(/views/shop/GoodsList.vue) }, { path: order, component: () import(/views/shop/OrderList.vue) } ] }有几个关键点需要说明。第一父路由的path可以不带斜杠结尾但必须是一个合法的路径前缀。访问/shop/goods时Vue Router 会先渲染父组件ShopLayout.vue再把子组件GoodsList.vue渲染到父组件的RouterView /中。第二children中的子路径不用写/开头直接写相对路径goods即可它会自动拼接shop/goods。如果你写了/goods会被当成根路径下的路由访问/shop/goods时反而匹配不到最后大概率落入 404 兜底页面。第三父路由要么带一个默认重定向redirect要么配置一个path: 的空子路由来兜底。否则访问/shop时只会渲染父组件的空壳内容区一片空白。我常写两种方案个人更推荐redirect语义更清晰。2.3 动态路由与 props 传参动态路由指路径中包含参数的路由经典场景是详情页/user/123和/user/456要渲染同一个组件只是组件内部根据不同 ID 拉取不同数据。{ path: /user/:id, name: UserDetail, component: () import(/views/user/Detail.vue), props: true }这里最有价值的一个配置是props: true。它的作用是把路由参数自动变成组件的 props 传入。组件内可以直接声明defineProps([id])来接收不再需要从route.params.id里手动读取。如果你不写props: true组件里要这样拿参数const route useRoute() const id route.params.id切到 props 写法后组件更干净也更容易做单元测试——直接给组件传 props 就能渲染不用再构造一个路由对象。我建议路由参数只用于组件内部数据获取时用props: true。如果组件内部还要访问完整的$route对象或者要用 query 参数那props: true就解决不了所有场景可以部分接受props: { from: list }。2.4 redirect 与 alias 的区分redirect是重定向访问 A 路径时实际跳转到 B 路径。常见场景是首页/重定向到某个具体页面以及兼容旧地址比如以前是/product改版后变成/goods/list可以用重定向把老链接导过去。alias是别名访问别名时URL 保持别名不变但渲染的是目标路由的组件。比如{ path: /goods/list, name: GoodsList, component: () import(/views/goods/List.vue), alias: /product }访问/product时地址栏依然是/product但页面渲染的是GoodsList组件。这适合不想让用户看出路由结构变化的场景。redirect会改变地址栏alias不会两者别搞混了。3. 路由守卫与权限控制的组合玩法路由守卫是“在页面跳转前执行一段逻辑”的钩子。我实际项目里最常用的场景是登录判断和动态菜单权限。路由守卫用好了权限控制会变得很优雅。3.1 全局前置守卫的登录拦截先看一个最基础的需求用户未登录时访问任何需要登录的页面都强制跳转到登录页并带上当前地址作为登录后的回跳路径。router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.meta.requiresAuth !token) { next({ name: Login, query: { redirect: to.fullPath } }) return } next() })这里要强调的是next只在需要中断跳转时才显式调用其他情况直接返回即可。Vue Router 4 的守卫里next()如果不调用跳转会一直挂起页面一直转圈。我看到过不少同事在beforeEach里写了多个分支却漏了某个return next()结果整个前端“瘫痪”排查半天才发现是守卫把跳转拦住了。登录成功后回跳的实现也很简单在登录组件里取route.query.redirect然后跳回去const redirect route.query.redirect || / router.push(redirect)这里有个安全小细节尽量不要直接用router.push(redirect)去跳任意路径如果redirect里被塞了一个非法协议会有一定的开放重定向风险。严谨一点的做法是校验redirect以/开头。3.2 动态权限路由的 addRoute 方案后台系统里不同角色的用户看到的菜单和能访问的页面不一样。最简单的做法是前端把所有页面都注册到路由表里靠菜单显隐来控制展示。这方案容易实现但有个问题用户可以直接在地址栏输入他无权访问的路径页面照样能打开因为路由已经注册了。更严谨的做法是路由表只注册公开页面用户登录后拿到自己的权限列表再用addRoute动态注册他有权访问的路由。// 登录后请求权限接口返回当前用户可访问的页面路径列表 const permissionList [/user/profile, /shop/goods, /shop/order] permissionList.forEach(path { const route findRouteByPath(path) // 从完整的静态路由定义中找出对应记录 router.addRoute(route) })findRouteByPath通常是在项目里维护一份“完整路由定义”作为字典权限接口只返回路径字符串前端根据路径找到完整配置再动态注册。用动态路由方案时退出登录一定要记得重置路由表。我经历过的项目中就因为退出登录后没重置动态路由新登录的低权限用户访问旧的高权限路径时页面又是白屏又是跳错排查起来特别痛苦。清理方式是router.getRoutes().forEach(route { if (route.name isDynamicRouteName(route.name)) { router.removeRoute(route.name) } })3.3 全局后置守卫处理标题与进度条afterEach是全局后置守卫没有next不能中断跳转适合做一些跳转后的副作用。我常用的有三个设置页面标题、关闭全局 loading、上报埋点。router.afterEach((to, from) { const title to.meta.title ? ${to.meta.title}-某某系统 : 某某系统 document.title title // 关闭 loading loadingInstance.close() })beforeEach里打开 loadingafterEach里关闭 loading配合起来用户体验会很顺滑。这里注意afterEach拿不到next结构上要比前置守卫简单。3.4 路由守卫的执行顺序多个路由守卫同时存在时执行顺序很多人分不清。以“全局前置守卫、组件内守卫、全局后置守卫”组合为例一次完整的跳转流程是全局beforeEach被导航离开的组件内beforeRouteLeave新路由组件内beforeRouteUpdate如果复用同一组件新路由组件内beforeRouteEnter全局beforeResolve导航被确认全局afterEach我只强调一个最常用的经验想在导航被完全确认前做最后一道检查可以放在beforeResolve里比如按页面代码分割的动态导入失败时的兜底刷新逻辑。日常项目里用beforeEach加afterEach基本就够覆盖绝大多数需求了。4. 路由懒加载与性能优化实践路由懒加载是 SPA 性能优化的一个重要手段原则很简单让首屏只加载首屏需要的代码其他页面代码等真正被访问时再加载。4.1 懒加载的几种写法与坑Vue Router 的懒加载写法是利用动态import(){ path: /home, component: () import(/views/Home.vue) }打包时Vite 或 Webpack 会自动把这些动态导入的组件拆成独立 chunk首屏加载index.js时不会包含 Home 以外的页面代码。有人会把组件包一层箭头函数然后返回 import比如component: () import(/views/Home.vue).then(m m.default)这种写法在 Vue 2 的某些模块系统里是必须的因为在 Vue 2 Webpack 早期版本里动态 import 返回的是模块命名空间对象需要取.default才是组件本身。但在 Vue 3 里直接写() import(/views/Home.vue)就行Vue Router 会自动处理好默认导出不需要再手动取.default。多写那层then不仅没必要还可能因为命名不一致导致懒加载组件渲染不出来。还有一种需要避免的写法是component: () { return import(/views/Home.vue) }意思一样但多套了一层无用的函数体完全没必要代码也更绕。懒加载直接写成箭头函数返回 import 是最干净最直观的。4.2 路由级的 webpackChunkName 分包生产项目中打包后你会看到一堆长哈希文件名的 JS 文件很难从文件名判断属于哪个页面。给懒加载路由加注释可以让打包工具把代码块命名清楚方便定位体积来源。{ path: /home, component: () import(/* webpackChunkName: home */ /views/Home.vue) }Vite 里对应的写法是component: () import(/views/Home.vue)Vite 是基于文件名自动生成 chunk 名的无需额外注释也能在构建产物里看到可读的文件名。我实际做性能优化时经常用构建产物分析工具看每个 chunk 的体积。如果一个页面组件引了一个巨型的第三方图表库那这个页面的路由 chunk 会大得吓人。这时要么把图表库单独分包做 CDN要么用组件异步加载把图表库拆出页面主体。路由懒加载只是优化策略的一层真正细致的优化要看分析和拆包。4.3 滚动行为优化SPA 切换路由时默认滚动位置会停留在切换前的位置。用户从很长的列表页点进详情页再返回列表时会发现页面定位到了半截位置体验很差。Vue Router 提供了scrollBehavior配置写一次全局生效const router createRouter({ history: createWebHistory(), routes, scrollBehavior(to, from, savedPosition) { if (savedPosition) { return savedPosition } else { return { top: 0 } } } })savedPosition是浏览器记录的上次滚动位置用户点击前进后退时会自动恢复。普通的路由跳转会回到页面顶部。注意一个问题如果你使用的是keep-alive缓存组件滚动位置不会自动恢复。因为组件被缓存了DOM 还是旧的那份scrollBehavior只能作用在路由切换后重新渲染的页面。这种情况下需要在activated钩子里手动恢复滚动位置比如onActivated(() { window.scrollTo(0, savedScrollTop.value) })4.4 路由过渡动画的配置Vue 3 中给路由组件加切换动画只需要在RouterView外层包一个Transitionrouter-view v-slot{ Component } transition namefade modeout-in component :isComponent / /transition /router-view配合路由 meta 实现不同页面间不同动画也是常用方案router-view v-slot{ Component, route } transition :nameroute.meta.transition || fade modeout-in component :isComponent / /transition /router-view动态切换动画有一个明显的坑两个路由的切换方向不同从 A 进 B 和从 B 退 A动画应该相反。如果只是固定一个动画名返回时的动效会显得很别扭。我项目里一般是把动画名和层级绑定比如在 meta 里维护一个 order 字段切换时比较两个路由的 order 大小来决定前进动画还是后退动画。5. 常见问题排查与避坑记录最后这部分是我压箱底的排查笔记。这些问题是路由配置里踩坑率最高的几个每个我都在真实项目中撞到过而且每个的报错信息都极具迷惑性。5.1 刷新页面 404现象开发环境一切正常一部署到服务器在/user/profile页面刷新就 404。原因服务器上不存在/user/profile这个物理路径服务器找不到文件默认返回 404。排查这个问题的排查顺序很清晰。第一步看地址栏是#模式还是无#模式。如果是 Hash 模式还 404那问题在别处比如静态资源相对路径错误。如果是 History 模式几乎可以断定是服务器的try_files配置没生效。解决让后端把try_files $uri $uri/ /index.html;配上。如果项目部署在二级路径下比如https://example.com/app/那么 Vue Router 创建实例时也要加createWebHistory(/app/)前缀同时静态资源 base 路径也要对应调整。5.2 连续点击菜单报重复路由错误现象点击菜单跳转时控制台出现[Vue Router warn]: No match found for location with path /home或者干脆没有报错但页面没变化。原因一个常见情况是重复跳转到当前路由。Vue Router 4 对跳转目标等同于当前路由的行为是拒绝的如果你在菜单点击事件里无条件执行router.push(/home)第二次点击时就会触发这条警告。还有一个隐蔽的情况路径匹配失败。比如路由表里定义的是/home但导航链接里写成了/Home大小写不匹配也会报这个错。解决菜单点击跳转前判断一下当前路径const goHome () { if (route.path /home) return router.push(/home) }或者统一在router.push的 Promise 上做 catch因为 rejected promise 如果不处理控制台会一直挂红router.push(/home).catch(() {})5.3 动态 addRoute 后页面白屏现象登录后动态注册了权限路由但手动输入/shop/goods地址刷新后页面空白控制台也不报错。原因刷新时应用重新加载路由表恢复到初始状态只包含公开路由。此时地址是/shop/goods却没有对应路由匹配渲染区域内没有任何组件于是白屏。排查这种问题一定要先看路由表。在代码里打印router.getRoutes()看看目标路径是否在表里。不在说明动态注册逻辑没有在应用加载第一时间执行。解决在应用初始化时先拿本地 token 请求用户权限然后动态注册路由最后再执行初始跳转。顺序非常重要一定不能等app.mount(#app)全部跑完才去注册动态路由。可以用一个异步初始化函数来组织async function bootstrap() { const token localStorage.getItem(token) if (token) { const perms await fetchUserPermissions() perms.forEach(path router.addRoute(findRouteByPath(path))) } app.use(router) router.isReady().then(() { app.mount(#app) }) }注意router.isReady()在动态路由场景里是必需的。它保证初始导航完成后再挂载应用否则首次渲染的页面可能不是正确的路由页面。5.4 404 兜底路由的写法很多项目习惯在路由表最后加一个通配路由来做 404 兜底{ path: /:pathMatch(.*)*, component: () import(/views/NotFound.vue) }这个写法在 Vue Router 4 里是官方推荐的。Vue 2 时代写*在 Vue Router 4 里必须改成/:pathMatch(.*)*因为 Vue Router 4 移除了对旧风格通配符的支持。pathMatch可以把用户访问的任意路径捕获到你甚至可以在 404 组件里通过route.params.pathMatch拿到用户真实输入的路径做“该页面不存在”的提示。警惕一个配套问题如果你给 404 兜底路由加了name并且被addRoute误注册成动态路由权限清理时可能会把 404 路由一起删掉导致所有未匹配路径都变成空白。我的经验是 404 兜底路由一律作为静态路由放在路由表的固定位置永远不进动态注册流程。5.5 keep-alive 与路由 meta 缓存控制后台系统里列表页通常会缓存详情页不缓存切换回来列表还能保留滚动位置和筛选条件。这个需求一般结合keep-alive的include配置实现用路由的name作为缓存标识。router-view v-slot{ Component } keep-alive :includecachedNames component :isComponent / /keep-alive /router-viewcachedNames是一个数组内容是需要缓存的路由name比如[GoodsList]。注意include匹配的是组件名称name不是路由的name。如果你在组件内没有定义defineOptions({ name: GoodsList })那include就失效了页面永远不会被缓存。这是我见过的最隐蔽的一个坑路由配置里写了name就默认组件也会被缓存但实际缓存机制认的是组件自身名称结果排查了半个小时发现只是忘了给组件文件加 name。5.6 路由切换后 getCurrentInstance 报错现象在组件模板里用useRoute()完全正常但直接在普通 JavaScript 文件里调用useRoute()报错getCurrentInstance is not defined。原因useRoute只能在组件上下文里用普通工具函数文件里没有组件实例环境。解决工具函数需要访问当前路由时不要用useRoute改成从入口注入 router 或者用router.currentRoute.valueimport router from /router export function getCurrentPagePath() { return router.currentRoute.value.path }router.currentRoute是响应式的 Ref.value才是当前的路由对象。注意如果用解构的方式从router.currentRoute.value取值响应性会丢失这是另一个坑尤其在watch路由参数变化时特别容易踩到。写在最后路由配置看着简单其实每一块都藏着不少细节。我这些年最深刻的一个体会是路由表不只是技术配置它更是一种接口约定。后端接口的路径、前端页面的路径、权限控制的标识、埋点统计的编号全都能在路由配置里找到汇合点。一个好的路由配置设计能在项目初期就替后续的权限接入、性能优化、异常排查省下大量时间。上面列出的每一个问题都是我实际开发里撞出来、写进排查笔记的。如果你在项目里遇到类似现象可以直接对照着查大概率能快速定位问题所在。最想提醒大家的一点是遇到路由相关的怪问题先去打印router.getRoutes()看路由表再去确认服务器部署配置不要在组件里一层层排查浪费太多时间。路由是前端基础设施越早定位到问题修复成本越低。 
长河君 · 2026/10/18 9:50:08 · 阅读 1.2k Vue 3 + Vue Router 4 路由配置完全指南：从入门到避坑
做 Vue 开发绕不开的就是路由配置。我在项目中不管接手的是后台管理系统还是 H5 活动页第一件事永远是打开路由配置文件从上往下扫一遍。路由配置写得好不好直接决定后续加页面、加权限、做埋点时是“改一行配置就行”还是“到处打补丁”。这篇文章我就把 Vue 3 Vue Router 4 的路由配置完整拆开讲一遍从基础的路由表设计到嵌套路由、动态路由、路由守卫、懒加载再到我实际开发中踩过的坑和排查方法尽量写成可以直接照抄的经验文档。不管你是刚学 Vue 还没搞明白routes数组里每一行是什么意思的新手还是已经在项目里写过路由但遇到刷新 404、重复跳转报错、动态加路由白屏这些怪问题的开发者这篇文章应该都能对你有用。1. 路由配置的核心思路拆解1.1 路由到底在解决什么问题先说个最简单的场景。传统多页面开发时浏览器地址栏从/index.html切到/about.html实际上是向服务器发起两次请求服务器返回两个不同的 HTML 文件。SPA 单页应用只有一个index.html你要从首页切到关于页不能再请求服务器了只能由前端 JavaScript 自己根据地址栏的变化动态替换页面上的内容组件。这个时候就需要一个“地址映射规则表”也就是路由配置。Vue Router 做的事就是把“URL 路径”和“组件”绑定起来路径是/home就渲染 Home 组件路径是/user/profile就渲染 UserProfile 组件。它还额外处理了浏览器的前进后退、页面刷新时的状态恢复、路由切换过程中的拦截逻辑等。理解这个本质再看路由配置里的每一项参数就不会觉得是在死记配置 API而是在真的设计一张映射表。1.2 路由模式选择History 与 Hash 各自的取舍Vue Router 4 创建路由实例时最常见的两个模式是createWebHistory和createWebHashHistory。import { createRouter, createWebHistory } from vue-router const router createRouter({ history: createWebHistory(), routes: [] })createWebHistory模式生成的 URL 长这样https://example.com/user/profile地址栏干净清爽也是我在项目中的默认选择。但它有一个前提条件后端服务器必须把所有非文件资源的请求都重定向到index.html。因为用户访问/user/profile时服务器上并不存在这个物理路径如果你不做重定向用户一刷新页面浏览器拿到的就是 404。生产环境中这个配置通常在 Nginx 里处理常见写法是location / { try_files $uri $uri/ /index.html; }createWebHashHistory模式的 URL 是https://example.com/#/user/profile#后面的内容不会发送到服务器所以刷新页面不会有 404 问题。缺点是地址栏不好看且#之后的路径变化在某些业务场景下做埋点、做分享链接会麻烦一些。我的建议很简单能保证后端配合就优先用 History 模式图省事或者后端不好改就用 Hash 模式。两种模式只是路由实例的入参不同后面的routes数组配置完全一致后续想切换成本很低。1.3 路由配置文件的组织方式项目小的时候所有路由写在一个router/index.js里还能接受。项目一旦超过几十个页面全堆在一起就非常痛苦每次看路由表要滚动很久。我习惯把路由表按业务模块拆成独立文件再用main.ts统一整合。比如一个电商项目可以拆出user.ts、order.ts、product.ts三个模块路由文件// router/modules/user.ts export default [ { path: /user, component: () import(/layouts/UserLayout.vue), children: [ { path: , redirect: /user/profile }, { path: profile, component: () import(/views/user/Profile.vue) }, { path: address, component: () import(/views/user/Address.vue) } ] } ]// router/index.ts import { createRouter, createWebHistory } from vue-router import userRoutes from ./modules/user import orderRoutes from ./modules/order import productRoutes from ./modules/product const router createRouter({ history: createWebHistory(), routes: [ { path: /, redirect: /home }, { path: /home, component: () import(/views/Home.vue) }, ...userRoutes, ...orderRoutes, ...productRoutes ] })这种写法有几个好处第一不同业务线的路由由对应负责人维护Git 冲突明显减少。第二路由配置和业务目录结构能保持同步。第三后续如果要按模块做权限控制也可以直接把某个模块的路由整体加到权限配置里。2. routes 数组配置项详解routes数组是路由配置的核心数组里的每一项都是一个路由记录对象。我在 code review 时发现很多新人会把每条路由都写成一样的模板不太清楚某些字段到底在什么场景用。下面按我实际使用的频率来逐个说。2.1 最常用的基础配置项一个最典型的配置项组合是{ path: /product/detail/:id, name: ProductDetail, component: () import(/views/product/Detail.vue), meta: { title: 商品详情, requiresAuth: true } }path是路径支持静态路径和动态参数动态参数用冒号声明比如:id。name是路由名称后续跳转用router.push({ name: ProductDetail, params: { id: 1 } })时会比直接拼路径字符串更安全——路径变了路由名不变代码就不用改。meta是一个只做信息承载的对象官方称之为“路由元信息”。我习惯把页面标题、是否需要登录、页面权限标识、埋点编号等非路由逻辑的数据都放进去。页面标题可以在全局守卫里读取权限标识则可以配合登录状态做拦截判断。这里有一个容易踩的细节name必须是全局唯一的不能两个路由记录用同一个name。否则 Vue Router 会报一条警告并且跳转时会拿到最先匹配的那个记录行为会变得非常诡异。2.2 嵌套路由与子路由配置后台管理系统几乎必用嵌套路由。原因在于后台页面通常有一个统一的侧边栏和顶部栏骨架只有中间内容区随路由变化。如果你不做嵌套路由侧边栏的展示逻辑就要在每个页面组件里写一遍非常臃肿。嵌套路由的写法是在父路由上加children{ path: /shop, component: () import(/layouts/ShopLayout.vue), redirect: /shop/goods, children: [ { path: goods, component: () import(/views/shop/GoodsList.vue) }, { path: order, component: () import(/views/shop/OrderList.vue) } ] }有几个关键点需要说明。第一父路由的path可以不带斜杠结尾但必须是一个合法的路径前缀。访问/shop/goods时Vue Router 会先渲染父组件ShopLayout.vue再把子组件GoodsList.vue渲染到父组件的RouterView /中。第二children中的子路径不用写/开头直接写相对路径goods即可它会自动拼接shop/goods。如果你写了/goods会被当成根路径下的路由访问/shop/goods时反而匹配不到最后大概率落入 404 兜底页面。第三父路由要么带一个默认重定向redirect要么配置一个path: 的空子路由来兜底。否则访问/shop时只会渲染父组件的空壳内容区一片空白。我常写两种方案个人更推荐redirect语义更清晰。2.3 动态路由与 props 传参动态路由指路径中包含参数的路由经典场景是详情页/user/123和/user/456要渲染同一个组件只是组件内部根据不同 ID 拉取不同数据。{ path: /user/:id, name: UserDetail, component: () import(/views/user/Detail.vue), props: true }这里最有价值的一个配置是props: true。它的作用是把路由参数自动变成组件的 props 传入。组件内可以直接声明defineProps([id])来接收不再需要从route.params.id里手动读取。如果你不写props: true组件里要这样拿参数const route useRoute() const id route.params.id切到 props 写法后组件更干净也更容易做单元测试——直接给组件传 props 就能渲染不用再构造一个路由对象。我建议路由参数只用于组件内部数据获取时用props: true。如果组件内部还要访问完整的$route对象或者要用 query 参数那props: true就解决不了所有场景可以部分接受props: { from: list }。2.4 redirect 与 alias 的区分redirect是重定向访问 A 路径时实际跳转到 B 路径。常见场景是首页/重定向到某个具体页面以及兼容旧地址比如以前是/product改版后变成/goods/list可以用重定向把老链接导过去。alias是别名访问别名时URL 保持别名不变但渲染的是目标路由的组件。比如{ path: /goods/list, name: GoodsList, component: () import(/views/goods/List.vue), alias: /product }访问/product时地址栏依然是/product但页面渲染的是GoodsList组件。这适合不想让用户看出路由结构变化的场景。redirect会改变地址栏alias不会两者别搞混了。3. 路由守卫与权限控制的组合玩法路由守卫是“在页面跳转前执行一段逻辑”的钩子。我实际项目里最常用的场景是登录判断和动态菜单权限。路由守卫用好了权限控制会变得很优雅。3.1 全局前置守卫的登录拦截先看一个最基础的需求用户未登录时访问任何需要登录的页面都强制跳转到登录页并带上当前地址作为登录后的回跳路径。router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.meta.requiresAuth !token) { next({ name: Login, query: { redirect: to.fullPath } }) return } next() })这里要强调的是next只在需要中断跳转时才显式调用其他情况直接返回即可。Vue Router 4 的守卫里next()如果不调用跳转会一直挂起页面一直转圈。我看到过不少同事在beforeEach里写了多个分支却漏了某个return next()结果整个前端“瘫痪”排查半天才发现是守卫把跳转拦住了。登录成功后回跳的实现也很简单在登录组件里取route.query.redirect然后跳回去const redirect route.query.redirect || / router.push(redirect)这里有个安全小细节尽量不要直接用router.push(redirect)去跳任意路径如果redirect里被塞了一个非法协议会有一定的开放重定向风险。严谨一点的做法是校验redirect以/开头。3.2 动态权限路由的 addRoute 方案后台系统里不同角色的用户看到的菜单和能访问的页面不一样。最简单的做法是前端把所有页面都注册到路由表里靠菜单显隐来控制展示。这方案容易实现但有个问题用户可以直接在地址栏输入他无权访问的路径页面照样能打开因为路由已经注册了。更严谨的做法是路由表只注册公开页面用户登录后拿到自己的权限列表再用addRoute动态注册他有权访问的路由。// 登录后请求权限接口返回当前用户可访问的页面路径列表 const permissionList [/user/profile, /shop/goods, /shop/order] permissionList.forEach(path { const route findRouteByPath(path) // 从完整的静态路由定义中找出对应记录 router.addRoute(route) })findRouteByPath通常是在项目里维护一份“完整路由定义”作为字典权限接口只返回路径字符串前端根据路径找到完整配置再动态注册。用动态路由方案时退出登录一定要记得重置路由表。我经历过的项目中就因为退出登录后没重置动态路由新登录的低权限用户访问旧的高权限路径时页面又是白屏又是跳错排查起来特别痛苦。清理方式是router.getRoutes().forEach(route { if (route.name isDynamicRouteName(route.name)) { router.removeRoute(route.name) } })3.3 全局后置守卫处理标题与进度条afterEach是全局后置守卫没有next不能中断跳转适合做一些跳转后的副作用。我常用的有三个设置页面标题、关闭全局 loading、上报埋点。router.afterEach((to, from) { const title to.meta.title ? ${to.meta.title}-某某系统 : 某某系统 document.title title // 关闭 loading loadingInstance.close() })beforeEach里打开 loadingafterEach里关闭 loading配合起来用户体验会很顺滑。这里注意afterEach拿不到next结构上要比前置守卫简单。3.4 路由守卫的执行顺序多个路由守卫同时存在时执行顺序很多人分不清。以“全局前置守卫、组件内守卫、全局后置守卫”组合为例一次完整的跳转流程是全局beforeEach被导航离开的组件内beforeRouteLeave新路由组件内beforeRouteUpdate如果复用同一组件新路由组件内beforeRouteEnter全局beforeResolve导航被确认全局afterEach我只强调一个最常用的经验想在导航被完全确认前做最后一道检查可以放在beforeResolve里比如按页面代码分割的动态导入失败时的兜底刷新逻辑。日常项目里用beforeEach加afterEach基本就够覆盖绝大多数需求了。4. 路由懒加载与性能优化实践路由懒加载是 SPA 性能优化的一个重要手段原则很简单让首屏只加载首屏需要的代码其他页面代码等真正被访问时再加载。4.1 懒加载的几种写法与坑Vue Router 的懒加载写法是利用动态import(){ path: /home, component: () import(/views/Home.vue) }打包时Vite 或 Webpack 会自动把这些动态导入的组件拆成独立 chunk首屏加载index.js时不会包含 Home 以外的页面代码。有人会把组件包一层箭头函数然后返回 import比如component: () import(/views/Home.vue).then(m m.default)这种写法在 Vue 2 的某些模块系统里是必须的因为在 Vue 2 Webpack 早期版本里动态 import 返回的是模块命名空间对象需要取.default才是组件本身。但在 Vue 3 里直接写() import(/views/Home.vue)就行Vue Router 会自动处理好默认导出不需要再手动取.default。多写那层then不仅没必要还可能因为命名不一致导致懒加载组件渲染不出来。还有一种需要避免的写法是component: () { return import(/views/Home.vue) }意思一样但多套了一层无用的函数体完全没必要代码也更绕。懒加载直接写成箭头函数返回 import 是最干净最直观的。4.2 路由级的 webpackChunkName 分包生产项目中打包后你会看到一堆长哈希文件名的 JS 文件很难从文件名判断属于哪个页面。给懒加载路由加注释可以让打包工具把代码块命名清楚方便定位体积来源。{ path: /home, component: () import(/* webpackChunkName: home */ /views/Home.vue) }Vite 里对应的写法是component: () import(/views/Home.vue)Vite 是基于文件名自动生成 chunk 名的无需额外注释也能在构建产物里看到可读的文件名。我实际做性能优化时经常用构建产物分析工具看每个 chunk 的体积。如果一个页面组件引了一个巨型的第三方图表库那这个页面的路由 chunk 会大得吓人。这时要么把图表库单独分包做 CDN要么用组件异步加载把图表库拆出页面主体。路由懒加载只是优化策略的一层真正细致的优化要看分析和拆包。4.3 滚动行为优化SPA 切换路由时默认滚动位置会停留在切换前的位置。用户从很长的列表页点进详情页再返回列表时会发现页面定位到了半截位置体验很差。Vue Router 提供了scrollBehavior配置写一次全局生效const router createRouter({ history: createWebHistory(), routes, scrollBehavior(to, from, savedPosition) { if (savedPosition) { return savedPosition } else { return { top: 0 } } } })savedPosition是浏览器记录的上次滚动位置用户点击前进后退时会自动恢复。普通的路由跳转会回到页面顶部。注意一个问题如果你使用的是keep-alive缓存组件滚动位置不会自动恢复。因为组件被缓存了DOM 还是旧的那份scrollBehavior只能作用在路由切换后重新渲染的页面。这种情况下需要在activated钩子里手动恢复滚动位置比如onActivated(() { window.scrollTo(0, savedScrollTop.value) })4.4 路由过渡动画的配置Vue 3 中给路由组件加切换动画只需要在RouterView外层包一个Transitionrouter-view v-slot{ Component } transition namefade modeout-in component :isComponent / /transition /router-view配合路由 meta 实现不同页面间不同动画也是常用方案router-view v-slot{ Component, route } transition :nameroute.meta.transition || fade modeout-in component :isComponent / /transition /router-view动态切换动画有一个明显的坑两个路由的切换方向不同从 A 进 B 和从 B 退 A动画应该相反。如果只是固定一个动画名返回时的动效会显得很别扭。我项目里一般是把动画名和层级绑定比如在 meta 里维护一个 order 字段切换时比较两个路由的 order 大小来决定前进动画还是后退动画。5. 常见问题排查与避坑记录最后这部分是我压箱底的排查笔记。这些问题是路由配置里踩坑率最高的几个每个我都在真实项目中撞到过而且每个的报错信息都极具迷惑性。5.1 刷新页面 404现象开发环境一切正常一部署到服务器在/user/profile页面刷新就 404。原因服务器上不存在/user/profile这个物理路径服务器找不到文件默认返回 404。排查这个问题的排查顺序很清晰。第一步看地址栏是#模式还是无#模式。如果是 Hash 模式还 404那问题在别处比如静态资源相对路径错误。如果是 History 模式几乎可以断定是服务器的try_files配置没生效。解决让后端把try_files $uri $uri/ /index.html;配上。如果项目部署在二级路径下比如https://example.com/app/那么 Vue Router 创建实例时也要加createWebHistory(/app/)前缀同时静态资源 base 路径也要对应调整。5.2 连续点击菜单报重复路由错误现象点击菜单跳转时控制台出现[Vue Router warn]: No match found for location with path /home或者干脆没有报错但页面没变化。原因一个常见情况是重复跳转到当前路由。Vue Router 4 对跳转目标等同于当前路由的行为是拒绝的如果你在菜单点击事件里无条件执行router.push(/home)第二次点击时就会触发这条警告。还有一个隐蔽的情况路径匹配失败。比如路由表里定义的是/home但导航链接里写成了/Home大小写不匹配也会报这个错。解决菜单点击跳转前判断一下当前路径const goHome () { if (route.path /home) return router.push(/home) }或者统一在router.push的 Promise 上做 catch因为 rejected promise 如果不处理控制台会一直挂红router.push(/home).catch(() {})5.3 动态 addRoute 后页面白屏现象登录后动态注册了权限路由但手动输入/shop/goods地址刷新后页面空白控制台也不报错。原因刷新时应用重新加载路由表恢复到初始状态只包含公开路由。此时地址是/shop/goods却没有对应路由匹配渲染区域内没有任何组件于是白屏。排查这种问题一定要先看路由表。在代码里打印router.getRoutes()看看目标路径是否在表里。不在说明动态注册逻辑没有在应用加载第一时间执行。解决在应用初始化时先拿本地 token 请求用户权限然后动态注册路由最后再执行初始跳转。顺序非常重要一定不能等app.mount(#app)全部跑完才去注册动态路由。可以用一个异步初始化函数来组织async function bootstrap() { const token localStorage.getItem(token) if (token) { const perms await fetchUserPermissions() perms.forEach(path router.addRoute(findRouteByPath(path))) } app.use(router) router.isReady().then(() { app.mount(#app) }) }注意router.isReady()在动态路由场景里是必需的。它保证初始导航完成后再挂载应用否则首次渲染的页面可能不是正确的路由页面。5.4 404 兜底路由的写法很多项目习惯在路由表最后加一个通配路由来做 404 兜底{ path: /:pathMatch(.*)*, component: () import(/views/NotFound.vue) }这个写法在 Vue Router 4 里是官方推荐的。Vue 2 时代写*在 Vue Router 4 里必须改成/:pathMatch(.*)*因为 Vue Router 4 移除了对旧风格通配符的支持。pathMatch可以把用户访问的任意路径捕获到你甚至可以在 404 组件里通过route.params.pathMatch拿到用户真实输入的路径做“该页面不存在”的提示。警惕一个配套问题如果你给 404 兜底路由加了name并且被addRoute误注册成动态路由权限清理时可能会把 404 路由一起删掉导致所有未匹配路径都变成空白。我的经验是 404 兜底路由一律作为静态路由放在路由表的固定位置永远不进动态注册流程。5.5 keep-alive 与路由 meta 缓存控制后台系统里列表页通常会缓存详情页不缓存切换回来列表还能保留滚动位置和筛选条件。这个需求一般结合keep-alive的include配置实现用路由的name作为缓存标识。router-view v-slot{ Component } keep-alive :includecachedNames component :isComponent / /keep-alive /router-viewcachedNames是一个数组内容是需要缓存的路由name比如[GoodsList]。注意include匹配的是组件名称name不是路由的name。如果你在组件内没有定义defineOptions({ name: GoodsList })那include就失效了页面永远不会被缓存。这是我见过的最隐蔽的一个坑路由配置里写了name就默认组件也会被缓存但实际缓存机制认的是组件自身名称结果排查了半个小时发现只是忘了给组件文件加 name。5.6 路由切换后 getCurrentInstance 报错现象在组件模板里用useRoute()完全正常但直接在普通 JavaScript 文件里调用useRoute()报错getCurrentInstance is not defined。原因useRoute只能在组件上下文里用普通工具函数文件里没有组件实例环境。解决工具函数需要访问当前路由时不要用useRoute改成从入口注入 router 或者用router.currentRoute.valueimport router from /router export function getCurrentPagePath() { return router.currentRoute.value.path }router.currentRoute是响应式的 Ref.value才是当前的路由对象。注意如果用解构的方式从router.currentRoute.value取值响应性会丢失这是另一个坑尤其在watch路由参数变化时特别容易踩到。写在最后路由配置看着简单其实每一块都藏着不少细节。我这些年最深刻的一个体会是路由表不只是技术配置它更是一种接口约定。后端接口的路径、前端页面的路径、权限控制的标识、埋点统计的编号全都能在路由配置里找到汇合点。一个好的路由配置设计能在项目初期就替后续的权限接入、性能优化、异常排查省下大量时间。上面列出的每一个问题都是我实际开发里撞出来、写进排查笔记的。如果你在项目里遇到类似现象可以直接对照着查大概率能快速定位问题所在。最想提醒大家的一点是遇到路由相关的怪问题先去打印router.getRoutes()看路由表再去确认服务器部署配置不要在组件里一层层排查浪费太多时间。路由是前端基础设施越早定位到问题修复成本越低。