Vue Router 路由配置实战：从 history 模式到动态权限拦截的完整指南

1. 路由表的基础结构：history模式与routes数组的初始化

Vue路由配置看着简单，真正上手就会发现，多数坑都藏在最基础的那几行初始化代码里。先说说项目的路由是怎么被加载成页面的。Vue Router把URL地址解析成对应的组件，再把组件渲染到页面上，这个过程的起点就是createRouter创建的路由实例。

选history模式还是hash模式，是很多人第一次踩的坑。hash模式用得省心，地址栏带个#号，刷新页面不会出问题，因为#后面的内容本质上是浏览器端的状态。history模式地址干净好看，但刷新时服务器必须把任意路径都重定向到index.html，否则就会出现经典的404问题。在开发环境里Vite替我们做了这件事，生产环境部署到Nginx时需要加这样一段配置：

location / { try_files $uri $uri/ /index.html; }

这段配置的意思是：当服务器找不到对应的静态文件时，就返回index.html交给前端路由去解析。这个配置没做好，生产环境刷新页面就白屏，这是一条真实存在的生产事故链。

接下来看基础配置。一套能直接跑起来的路由表，包含了路由的三种核心要素：路径、组件引用、路由元信息。这里给一份我在脚手架项目里常用的初始化结构：

import { createRouter, createWebHistory } from 'vue-router' import Home from '../views/Home.vue' const routes = [ { path: '/', name: 'home', component: Home, meta: { title: '首页', requiresAuth: false } }, { path: '/user', name: 'user', component: () => import('../views/User.vue'), meta: { title: '用户中心', requiresAuth: true } } ] const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes }) router.beforeEach((to, from, next) => { document.title = to.meta.title ? `${to.meta.title} - 项目名` : '项目名' next() }) export default router

main.js里通过app.use(router)注册路由实例，这一步是Vue Router的插件机制在起作用，它会往全局注入两个组件RouterView和RouterLink，同时在组件实例上挂载$router和$route。

组件引用方式分成两种：静态引用和动态引入。import Home是静态引用，组件代码打进主包，首屏就要加载；() => import(...)是动态引入，Vite会把它单独切分成一个chunk，访问到这个路由时才加载对应模块。所以主页面用静态引用，二级页面全部用动态引入，这是路由表设计里的基本素养。

2. 路由参数传递与接收：query、params、动态路由三种玩法

路由参数是日常开发里躲不掉的部分，Vue Router提供了三种传参方式，适用的场景完全不同，混着用容易翻车。

query方式就是URL问号后面的参数，形如/user?id=123。接收方用route.query.id来拿值。query参数的特点是会暴露在地址栏里，能够被分享、被收藏，刷新之后依然有效。适合做筛选条件、搜索关键词、分页页码这些需要保留在URL中的状态。跳转时用router.push({ path: '/list', query: { page: 1 } })。这种方式不用在路由表里预定义，非常灵活，想传几个传几个。

params方式则完全不同。它的参数直接嵌在路径里，形如/user/123。要在路由表里预先定义好占位符：{ path: '/user/:id' }。跳转时用两种写法都可以：

router.push({ name: 'user', params: { id: 123 } }) // 或者 router.push(`/user/${123}`)

接收方用route.params.id拿值。这里有一个容易忽视的细节：如果用{ path: '/user', params: { id: 123 } }这种写法，params是不会被带上的！因为path直接指定了字符串路径，Vue Router就不再拿params做路径拼接了。这是很多人写了半天参数没传过去的头号原因。正确做法是用name加params的组合，或者直接拼字符串路径。

动态路由addRoute是第三种玩法，多用于权限控制的场景。后端返回当前用户有权限访问的菜单，前端把菜单对应的路由组件动态地挂进路由表：

function addDynamicRoutes(menus) { menus.forEach(menu => { router.addRoute({ path: menu.path, name: menu.name, component: () => import(`../views/${menu.componentName}.vue`) }) }) }

这种写法解决了静态路由表无法支撑权限差异的问题，但也有个显著的坑：动态添加的路由在页面刷新后会消失，因为路由表是内存状态，刷新后初始化回默认值。解决办法是把用户的菜单信息存到localStorage或者Pinia持久化里，刷新后在路由守卫里判断是否需要重新注册动态路由。

还有一个高频场景是路由参数变化时组件不刷新。举个例子，从/user/1跳转到/user/2，Vue Router会复用同一个组件实例，组件的created钩子不会再次执行，页面就停在旧数据的显示上。用watch监听route.params的变化来解决：

import { useRoute } from 'vue-router' import { watch } from 'vue' const route = useRoute() watch(() => route.params.id, (newId, oldId) => { fetchUserDetail(newId) })

这样参数变了就重新拉数据，页面表现就正常了。

3. 路由拦截器的配置逻辑：不做权限拦截的路由等于白写

路由拦截器的官方名称是导航守卫，用一句话说明它的能力：在路由跳转发生前和发生后插入自定义逻辑。最常用的是router.beforeEach，每次导航被触发时，解析完目标路由后调用。加上router.beforeResolve和router.afterEach，分别负责解析完成的节点和导航确认后的节点。

对于大多数后台管理项目，beforeEach承担了登录态校验和权限校验。一段典型的拦截逻辑：

router.beforeEach((to, from, next) => { const token = localStorage.getItem('token') if (to.meta.requiresAuth && !token) { next({ path: '/login', query: { redirect: to.fullPath } }) return } next() })

这段代码的逻辑是：目标路由标记了需要登录（requiresAuth为true），且本地没有token，就强制跳转到登录页，同时用query参数记录用户原本想去哪，登录成功后跳回原页面。这个设计模式在权限系统里非常常用。

afterEach在导航确定之后执行，但它拿不到next函数，也改不了导航结果。它适合做页面埋点、设置标题、滚动位置复位这些事：

router.afterEach((to, from) => { if (window._hmt && to.path.startsWith('/detail')) { window._hmt.push(['_trackPageview', to.fullPath]) } })

写了权限守卫之后，最多的报错是守卫死循环。这个错误的表现是页面一直跳转、浏览器报Maximum call stack size exceeded或者路由跳转超过重试次数。常见原因是在守卫里做了重定向，但重定向的目标路由自身又触发了同样的守卫逻辑，形成了A跳B、B跳A的循环。

举一个实际会踩到的例子：

router.beforeEach((to, from, next) => { const token = localStorage.getItem('token') if (!token) { next({ path: '/login' }) return } next() })

这段代码的问题在于：当用户访问/login页面且没有token时，每次访问都满足!token条件，于是next({ path: '/login' })把自己重定向给了自己，触发死循环。修复方式是在重定向前判断目标路由是不是已经是登录页：

router.beforeEach((to, from, next) => { const token = localStorage.getItem('token') if (!token && to.path !== '/login') { next({ path: '/login' }) return } next() })

另外，守卫里如果涉及异步操作（比如从后端拉取用户权限），必须保证异步完成后再调next()。在异步回调里调next()时要注意，一旦调用了next()就不应该再执行其他逻辑，否则多个next调用会引发不可预期的行为。

4. 404兜底、懒加载与滚动行为：这些细节配置决定了路由质量

很多人写路由表时，把通配路由放在数组最后面成了习惯，但为什么必须放最后？原因是Vue Router匹配路由时按数组顺序查找，通配路由/:pathMatch(.*)*能匹配任意路径，如果它排在最前面，后面所有精确路由就都失效了。所以通配路由永远放在数组最后，这个是铁律。

404兜底的完整配置在Vue Router 4.x的写法是：

{ path: '/:pathMatch(.*)*', name: 'not-found', component: () => import('../views/NotFound.vue'), meta: { title: '页面不存在' } }

/:pathMatch(.*)*这个写法有点特殊，pathMatch是参数名，:pathMatch表示捕获剩余路径，(.*)*里的星号让这个参数变成可选的，避免在某些场景下匹配出问题。如果只写/:pathMatch(.*)，在路由跳转时传给通配路由的参数会丢失，所以推荐带两个星号的写法。

路由懒加载在Vue 3项目里已经是标配。它的原理是Webpack或者Vite在构建时把动态import的模块单独打包，浏览器在首次加载时不请求这个模块，只有真正跳转到对应路由时才发请求。对首屏性能的改善非常直观——首屏加载的时间主要取决于主包体积，把页面组件全部打散成独立chunk之后，主包可以控制在一个很小的体积。

给懒加载一个适合项目的分块策略：

const routes = [ { path: '/list', component: () => import('../views/ListPage.vue'), children: [ { path: 'detail', component: () => import('../views/DetailPage.vue') } ] } ]

这里的建议是同一模块的页面放在相同目录结构下，import路径保持清晰。还有个小技巧，在import的注释里写/* webpackChunkName: "list" */可以自定义chunk名称，便于构建后分析哪些页面被单独打包了。Vite下则是通过rollupOptions.output.manualChunks来配置，效果类似。

路由滚动行为是很多项目没有配置但用户体验差别很大的点。从页面底部跳转到另一个页面时，新页面默认从顶部开始显示；但在列表页跳转详情页再返回，列表页的滚动位置往往已经重置到顶部。配置scrollBehavior可以在路由切换后恢复或者重置滚动位置：

const router = createRouter({ history: createWebHistory(), routes, scrollBehavior(to, from, savedPosition) { if (savedPosition) { return savedPosition } return { top: 0 } } })

savedPosition在用户通过浏览器前进/后退按钮跳转时会被浏览器自动记录，直接返回它就能恢复之前的滚动位置。对于tab切换、返回列表页这类交互，这个配置能省掉很多手动管理滚动位置的代码。

5. 嵌套路由与命名视图：复杂布局下路由配置的进阶玩法

后台管理项目的页面结构基本都是统一的：顶部导航、左侧菜单、右侧内容区。这种布局在路由配置里天然适合嵌套路由来处理。外层路由组件放布局骨架，内层路由组件放具体业务页面。

嵌套路由的配置结构：

{ path: '/layout', component: () => import('../layout/index.vue'), redirect: '/layout/dashboard', children: [ { path: 'dashboard', component: () => import('../views/Dashboard.vue'), meta: { title: '工作台' } }, { path: 'user', component: () => import('../views/User.vue'), meta: { title: '用户管理' } } ] }

外层组件里必须包含<RouterView />，子路由的内容才会被渲染到这个插槽里：

<template> <div class="layout"> <Sidebar /> <div class="main"> <Header /> <RouterView /> </div> </div> </template>

嵌套路由的一个细节问题：子路由的path是否带/。不带/时是相对路径，比如上面的'dashboard'最终完整路径是/layout/dashboard；如果写/dashboard，则完整路径变为/dashboard，彻底脱离了父路由的路径层级。而且带/的子路由对应的组件还会渲染到子层级，但因为路径变化导致父级组件被卸载，布局就没了。这个区别用一句话记住：子路由相对路径，不是绝对路径。

外层路由默认打开时，redirect字段指定重定向到的默认子路由，解决了访问/layout时没有匹配子路由的问题。

命名视图则是另一种思路，它允许一个路由下同时渲染多个组件到不同位置。写法上，把原来的component换成components（注意复数）：

{ path: '/search', components: { default: () => import('../views/SearchResult.vue'), sidebar: () => import('../views/SearchSidebar.vue'), footer: () => import('../views/SearchFooter.vue') } }

在布局组件中配合使用多个具名<RouterView>：

<RouterView /> <RouterView name="sidebar" /> <RouterView name="footer" />

默认的<RouterView />对应components里的default键。这个玩法适合页面不同区域分别管理、不同模块独立组件的场景，但一般情况下嵌套路由足够用了，命名视图用得不多。

嵌套路由跟权限拦截配合时，还有一个常见的需求：子路由都要求同一份权限校验。这种场景可以在外层路由的meta上设置requiresAuth: true，在beforeEach里判断to.matched.some(record => record.meta.requiresAuth)就行了。to.matched是一个数组，包含了从根路由到目标路由的所有嵌套层级记录，这样就不用在每个子路由上都单独标一次权限。

实际做菜单权限时，还会碰到动态路由结合嵌套路由的情况。动态注册嵌套子路由往往要先把父路由注册好，再利用父路由的name来挂子路由：

router.addRoute('layout', { path: 'report', component: () => import('../views/Report.vue'), meta: { title: '报表中心' } })

此时子路由需要嵌套在名为layout的父路由下，这个语法比直接嵌套在routes里灵活，适合做后端驱动的动态菜单权限系统。

技术选型层面的经验：Vue Router的路由表结构设计和项目规模直接相关，小型项目用扁平路由表加query传参够了，中大型后台系统才需要嵌套路由加动态路由权限控制。不要一上来就上复杂设计，等实际遇到布局和权限需求再上嵌套层级，维护成本会低很多。