Vue Router 重定向(Redirect)与别名(Alias)完整实战指南
Vue Router 重定向(Redirect)与别名(Alias)完整实战指南
本指南围绕 vue-router(Vue 2 官方路由)的 redirect 与 alias 两大路由配置能力展开,讲解如何在 routes 配置中实现路径跳转、命名路由跳转、动态跳转,以及在不改变 URL 的前提下复用已有组件与路由结构。读完本文,你将掌握重定向与别名的全部三种写法、二者的本质区别、底层匹配机制,以及来自仓库真实示例与源码的进阶用法。
重定向(Redirect):访问 A 跳转到 B
重定向直接在 routes 配置中完成,无需额外的代码逻辑。当用户访问 /a 时,URL 会被替换为 /b,随后按 /b 完成路由匹配与组件渲染。
基础写法:字符串路径重定向
从一个路径重定向到另一个路径,是最简单也最常用的形式:
const router = new VueRouter({
routes: [
{ path: '/a', redirect: '/b' }
]
})
命名路由重定向
当目标路由有 name 时,可以通过对象形式指向命名路由,避免硬编码路径:
const router = new VueRouter({
routes: [
{ path: '/a', redirect: { name: 'foo' } }
]
})
redirect: { name: 'foo' } 等价于把用户导航到名为 foo 的路由上。在 examples/redirect/app.js 中可以看到对应场景:/named-redirect 被配置为 redirect: { name: 'baz' },访问它最终渲染 /baz 对应的 Baz 组件。
动态重定向:函数形式
重定向目标也可以根据访问时的实际情况动态计算。函数接收目标路由(to)作为参数,需要返回一个路径字符串或一个 location 描述对象:
const router = new VueRouter({
routes: [
{ path: '/a', redirect: to => {
// 函数接收目标路由作为参数
// 在这里返回重定向的 path / location
}}
]
})
to 参数是一个完整的路由对象,包含 path、hash、query、params、name、fullPath 等字段。结合 examples/redirect/app.js 的 dynamic-redirect 示例,可以看到函数式重定向的典型用法:
{ path: '/dynamic-redirect/:id?',
redirect: to => {
const { hash, params, query } = to
if (query.to === 'foo') {
return { path: '/foo', query: null }
}
if (hash === '#baz') {
return { name: 'baz', hash: '' }
}
if (params.id) {
return '/with-params/:id'
} else {
return '/bar'
}
}
}
它同时演示了函数重定向的三种返回值风格:
- 返回 location 对象
{ path: '/foo', query: null },可精确控制 query 是否保留; - 返回命名路由对象
{ name: 'baz', hash: '' },并覆盖 hash; - 返回字符串
'/with-params/:id',路径中的:id会被自动填充为当前params.id。
重定向的底层实现:源码级解析
重定向在匹配阶段就被处理,核心逻辑位于 src/create-matcher.js 的 redirect() 函数。其执行流程如下:
- 若
redirect是函数,先以createRoute(record, location, null, router)构造出目标路由并作为参数传入,得到实际的重定向目标; - 若结果是字符串,统一转换为
{ path: redirect }对象; - 若结果无效(非对象、空值),在开发环境输出
invalid redirect option警告,并返回空路由; - 若目标是命名路由(
name存在),在nameMap中查找对应 record,找不到则断言失败(redirect failed: named route "..." not found.),找到则重新调用match()解析; - 若目标是路径(
path存在),依次执行三步:先通过resolveRecordPath解析相对路径,再用fillParams填充:params,最后携带原 query 与 hash 重新匹配。
关于 query、hash 的保留策略,源码第 121-124 行有明确规定:query、hash、params 默认继承自原始访问 location,只有重定向目标显式声明了对应字段(hasOwnProperty)时才覆盖。这也是示例中 { path: '/foo', query: null } 能显式清空 query 的原因。
每次经过重定向后,createRoute(见 src/util/route.js)会在最终路由对象上记录 redirectedFrom 字段,值为重定向前的完整路径。这意味着在组件里可以通过 $route.redirectedFrom 获知用户最初访问的地址,用于埋点、回跳等场景。
重定向的边界与注意点
- 导航守卫不会在发起重定向的路由上触发,只会在最终目标路由上生效。例如给
/a添加beforeEnter守卫,当/a重定向到/b时该守卫不会执行。详见 docs/guide/advanced/navigation-guards.md。 - 相对重定向:子路由可以使用相对路径重定向到同级兄弟路由,例如 examples/redirect/app.js 中
{ path: 'relative-redirect', redirect: 'foo' }会把/relative-redirect重定向到同级的/foo,且 query 会随重定向一并保留。 - 通配符兜底重定向:
{ path: '*', redirect: '/' }是最常见的 404 兜底方案,任何未匹配路径都会回到首页(见 examples/redirect/app.js)。 - 重定向带参数:
{ path: '/redirect-with-params/:id', redirect: '/with-params/:id' }会将参数透传给目标路径。 - 函数抛错会进入错误处理链路:测试 test/unit/specs/error-handling.spec.js 验证了当
redirect函数内部throw异常时,router.onError回调会被触发,push返回的 Promise 也会被 reject,因此不要在重定向函数中放置可能有副作用的逻辑而不做兜底。
别名(Alias):URL 不变,匹配不变
重定向意味着用户访问 /a 时 URL 被替换为 /b,然后按 /b 匹配。那么别名是什么呢?
/a 的别名为 /b,意味着用户访问 /b 时,URL 保持为 /b 不变,但路由匹配的结果与访问 /a 完全相同——渲染同样的组件、拥有同样的 $route 匹配记录。
在路由配置中表达为:
const router = new VueRouter({
routes: [
{ path: '/a', component: A, alias: '/b' }
]
})
别名的核心价值在于:它把 UI 结构与 URL 解耦,让你可以把同一套组件结构映射到任意 URL 上,而不必受路由配置嵌套结构的约束。典型场景包括:为旧版 URL 提供新入口、同一页面提供多个语义化路径、在不改变组件树的前提下调整对外路径。
别名的四种形态
examples/route-alias/app.js 完整演示了别名的各种写法:
1. 绝对路径别名(作用于顶层路由):
{ path: '/root', component: Root, alias: '/root-alias' }
访问 /root-alias 时 URL 保持 /root-alias,但渲染的是 /root 的 Root 组件。
2. 相对别名(作用于子路由,最终解析为父路径下的别名):
{ path: 'bar', component: Bar, alias: 'bar-alias' }
相对别名 bar-alias 会被解析为 /home/bar-alias,与父路由 /home 拼接。
3. 多个别名(数组形式):
{ path: 'baz', component: Baz, alias: ['/baz', 'baz-alias'] }
一个路由可以同时拥有多个别名,/baz 和 /home/baz-alias 都会渲染 Baz 组件。
4. 空字符串别名(配合默认子路由):
{ path: 'default', component: Default, alias: '' }
当父路由 /home 单独被访问时,匹配记录会落到这个默认子路由上——这是实现"父路径直接渲染默认子路由"的推荐写法。
嵌套别名
别名同样支持嵌套:父路由配置了别名后,其子路由路径会基于别名继续拼接。示例中:
{ path: 'nested', component: Nested, alias: 'nested-alias',
children: [
{ path: 'foo', component: NestedFoo }
]
}
访问 /home/nested-alias/foo 会渲染 /home/nested/foo 的组件树,URL 则保持 /home/nested-alias/foo 不变。
别名的源码实现:matchAs 机制
别名在 src/create-route-map.js 中构建路由表时处理。源码逻辑如下:
alias支持字符串或数组,统一规范化为数组;- 若别名与自身
path完全相同,开发环境会输出警告(Found an alias with the same value as the path)并跳过该别名,测试用例见 test/unit/specs/create-map.spec.js; - 每个别名都会被当作一条独立的
aliasRoute重新执行addRouteRecord,其matchAs参数被设为原记录的规范化路径(record.path || '/')——这正是别名机制的核心; - 由于别名记录与子路由记录都走
addRouteRecord,别名的子路径解析(childMatchAs拼接)与普通嵌套路由完全一致,从而支持嵌套别名。
在匹配阶段,src/create-matcher.js 的 alias() 函数拿到命中记录的 matchAs 后,用 fillParams 填充参数并基于别名路径重新 match,最终把匹配到的原始记录(而非别名记录)构造成路由返回。这样组件、守卫、matched 数组都以原始路由为准,URL 却保持别名不变。
重定向 vs 别名:一张表看懂区别
| 维度 | 重定向(redirect) | 别名(alias) |
|---|---|---|
访问 /a 时的 URL |
被替换为 /b |
保持 /b 不变 |
| 匹配结果 | 按 /b 匹配 |
按 /a 匹配 |
| 组件来源 | 目标路由的组件 | 原始路由的组件 |
| 主要用途 | 路径迁移、404 兜底、动态跳转 | 多 URL 映射同一 UI、保留旧入口 |
| 是否产生新导航 | 是,且记录 redirectedFrom |
否,一次导航完成 |
| 配置位置 | 路由记录上的 redirect 字段 |
路由记录上的 alias 字段 |
实战总结
- 需要改变 URL 时用重定向:路径重构、域名切换、登录后跳转、
*兜底,重定向是首选; - 需要保持 URL 时用别名:为同一页面提供多个入口路径、为深层嵌套路由提供简短访问地址时,别名能让 URL 与组件结构解耦;
- 两种能力都发生在匹配阶段:重定向在
match命中带redirect的记录后立即触发(src/create-matcher.js),别名则在命中带matchAs的记录后触发,二者由_createRoute统一调度,优先级为「先重定向、后别名」。
本文所有写法均可直接运行验证:仓库中的 examples/redirect/app.js 与 examples/route-alias/app.js 是完整的可运行示例,配套的 e2e 用例见 test/e2e/specs/redirect.js 与 test/e2e/specs/route-alias.js。建议动手修改配置,观察 URL 变化与渲染结果,以彻底掌握重定向与别名的行为差异。