Vue Router 2 重定向与别名完全指南:redirect 与 alias 的配置、源码原理与实战验证
Vue Router 2 重定向与别名完全指南:redirect 与 alias 的配置、源码原理与实战验证
导读:本指南以 vue-router(Vue 2 官方路由)官方文档中的「重定向与别名」章节为核心,系统讲解
routes配置中redirect(重定向)与alias(别名)的完整用法——包括路径字符串、命名路由对象、动态函数三种重定向形态,以及别名的绝对/相对路径、多别名与嵌套别名写法;同时结合仓库源码(src/create-route-map.js、src/create-matcher.js)与官方示例(examples/redirect/app.js、examples/route-alias/app.js)剖析二者的底层实现与本质差异。读完你将能精准判断"何时用重定向、何时用别名",并写出可投入生产的完整配置。
一、重定向(Redirect):在 routes 配置中完成的 URL 跳转
重定向可以直接在 routes 配置中声明,无需编写任何导航代码。路由配置中 redirect 选项支持三种形态:路径字符串、命名路由对象、动态函数。
1.1 字符串路径:最基础的重定向
将 /a 重定向到 /b:
const router = new VueRouter({
routes: [
{ path: '/a', redirect: '/b' }
]
})
访问 /a 时,URL 会被替换为 /b,随后路由系统以 /b 重新进行匹配。这一行为与源码中 _createRoute 的处理一致——匹配器在命中带有 redirect 的 route record 后,会立即调用 redirect() 函数并基于重定向目标再次执行 match:
// src/create-matcher.js#L183-L189
function _createRoute (record, location, redirectedFrom) {
if (record && record.redirect) {
return redirect(record, redirectedFrom || location)
}
if (record && record.matchAs) {
return alias(record, location, record.matchAs)
}
return createRoute(record, location, redirectedFrom, router)
}
1.2 命名路由对象:解耦路径字符串
重定向还可以指向一条命名路由,避免硬编码路径字符串,路径重构时更安全:
const router = new VueRouter({
routes: [
{ path: '/a', redirect: { name: 'foo' }}
]
})
从源码看,当 redirect 是对象且包含 name 时,redirect() 会直接从 nameMap 中查找目标 record,并对命名路由执行参数填充(fillParams)后再次匹配(src/create-matcher.js#L126-L138):
if (name) {
// resolved named redirect
const targetRecord = nameMap[name]
return match({
_normalized: true,
name,
query,
hash,
params
}, undefined, location)
}
该形态在 redirect 过程中会保留原位置的 query 与 hash(除非在重定向目标中显式覆盖),这是源码第 119-124 行明确的合并逻辑。
1.3 动态函数:根据目标路由决定去向
重定向也可以是一个函数,函数接收目标路由对象 to 作为参数(包含 params、query、hash、path、name 等),返回重定向的路径或 location 对象:
const router = new VueRouter({
routes: [
{ path: '/a', redirect: to => {
// 函数接收目标路由作为参数
// 在这里返回新的重定向路径 / location
}}
]
})
这是官方文档给出的最小骨架。仓库自带的 examples/redirect/app.js 给出了一个真实的完整实现,展示了基于 query、hash、params 的分支决策:
// examples/redirect/app.js
{ path: '/dynamic-redirect/:id?',
redirect: to => {
const { hash, params, query } = to
if (query.to === 'foo') {
return { path: '/foo', query: null } // 显式清空 query
}
if (hash === '#baz') {
return { name: 'baz', hash: '' } // 返回命名路由并清空 hash
}
if (params.id) {
return '/with-params/:id' // 携带参数重定向
} else {
return '/bar'
}
}
}
对应的端到端测试 test/e2e/specs/redirect.js 验证了上述行为:访问 /dynamic-redirect 落到 /bar,访问 /dynamic-redirect/123 落到 /with-params/123,访问 /dynamic-redirect?to=foo 落到 /foo,访问 /dynamic-redirect#baz 落到 /baz。
1.4 关键注意事项:导航守卫只作用于目标路由
重定向发生的源路由上不会执行导航守卫(Navigation Guards),守卫只在重定向的目标路由上生效。 例如,给 /a 添加 beforeEnter 守卫不会产生任何效果,因为重定向发生在守卫执行之前,匹配器直接换轨到目标路由。
const router = new VueRouter({
routes: [
{ path: '/a', redirect: '/b', beforeEnter: (to, from, next) => {
// 这段代码永远不会执行:/a 被重定向,不经过守卫
}},
{ path: '/b', component: B, beforeEnter: (to, from, next) => {
// 守卫写在这里才有效
}}
]
})
如果你希望在重定向前做拦截,应把守卫放在目标路由上,或借助全局守卫(beforeEach)结合 $route.redirectedFrom 判断来源(redirectedFrom 字段在 docs/api/README.md 中有说明,它是"发生重定向前的原始路由")。
二、进阶重定向实战:官方示例中的全部形态
官方示例 examples/redirect/app.js 覆盖了重定向的几乎所有进阶场景,是生产环境的最佳参考:
| 场景 | 配置 | 行为 |
|---|---|---|
| 兄弟路由的相对重定向 | { path: 'relative-redirect', redirect: 'foo' }(嵌套在 / 下) |
/relative-redirect → /foo,query 原样保留(?foo=bar 也会带过去) |
| 绝对路径重定向 | { path: '/absolute-redirect', redirect: '/bar' } |
/absolute-redirect → /bar |
| 带参数重定向 | { path: '/redirect-with-params/:id', redirect: '/with-params/:id' } |
/redirect-with-params/123 → /with-params/123,:id 被填充 |
| 动态函数重定向 | 见上文 redirect: to => { ... } |
基于 query / hash / params 分流 |
| 命名路由重定向 | { path: '/named-redirect', redirect: { name: 'baz' }} |
/named-redirect → /baz |
| 兜底重定向(catch-all) | { path: '*', redirect: '/' } |
未匹配的任何路径 → / |
其中两个值得注意的细节:
- 相对重定向基于当前路由的父路径解析。源码
resolveRecordPath(path, record)使用record.parent ? record.parent.path : '/'作为解析基准(src/create-matcher.js#L224-L226),所以嵌套路由内可以写不带前导/的相对路径。 - query 与 hash 的继承规则:字符串与函数重定向默认继承原地址的
query和hash;若想丢弃,需要在返回对象中显式置为null或空字符串(如示例中query: null、hash: '')。对象形态的重定向则可通过query、hash、params字段逐项覆盖。
三、别名(Alias):URL 保持不变,匹配走另一条路由
3.1 别名与重定向的本质区别
重定向意味着用户访问 /a 时,URL 被替换为 /b,随后按 /b 匹配;而别名恰恰相反——
把 /a 设为 /b 的别名,意味着用户访问 /b 时,URL 地址栏保持 /b 不变,但路由匹配结果等同于访问 /a。
const router = new VueRouter({
routes: [
{ path: '/a', component: A, alias: '/b' }
]
})
一句话总结两者的区别:
| 访问 URL | 地址栏 URL | 匹配目标 | 适用场景 | |
|---|---|---|---|---|
redirect |
/a |
变为 /b |
/b |
旧链接搬迁、SEO 301、兜底页 |
alias |
/b |
保持 /b |
/a(渲染 A 组件) |
同一 UI 对应多个 URL、嵌套结构束缚 |
别名的核心价值在于:它让你可以把一套 UI 结构自由映射到任意 URL,而不被路由配置的嵌套结构所约束。 例如,组件深藏在 /home/foo 的嵌套层级里,你依然可以让它同时响应 /foo 这个扁平、友好的地址。
3.2 别名的源码实现:matchAs 机制
从源码看,别名的实现并不复杂却非常巧妙。在 src/create-route-map.js#L152-L178 中,addRouteRecord 会为每一个别名单独注册一条"别名路由记录",并把原始路径作为 matchAs 传入:
if (route.alias !== undefined) {
const aliases = Array.isArray(route.alias) ? route.alias : [route.alias]
for (let i = 0; i < aliases.length; ++i) {
const alias = aliases[i]
const aliasRoute = {
path: alias,
children: route.children
}
addRouteRecord(
pathList, pathMap, nameMap, aliasRoute, parent,
record.path || '/' // matchAs
)
}
}
当 URL 命中别名记录时,_createRoute 检测到 record.matchAs 存在,便调用 alias() 函数(src/create-matcher.js#L159-L176):它用 matchAs(即原始路径)重新匹配一次,取出匹配链的最后一个 record 作为渲染结果,同时把原始位置的 URL 保留下来:
function alias (record, location, matchAs) {
const aliasedPath = fillParams(matchAs, location.params, `aliased route with path "${matchAs}"`)
const aliasedMatch = match({ _normalized: true, path: aliasedPath })
if (aliasedMatch) {
const matched = aliasedMatch.matched
const aliasedRecord = matched[matched.length - 1]
location.params = aliasedMatch.params
return _createRoute(aliasedRecord, location) // location 仍是别名 URL
}
return _createRoute(null, location)
}
这就是"URL 不变、组件照常渲染"的底层原理——这也是为什么别名不会触发 URL 变化、不会产生新的历史记录,与重定向(会替换 URL、push 一条新记录)形成鲜明对比。
3.3 别名的进阶形态
官方示例 examples/route-alias/app.js 完整演示了别名的四种进阶写法:
const router = new VueRouter({
mode: 'history',
routes: [
// 1. 绝对路径别名
{ path: '/root', component: Root, alias: '/root-alias' },
{ path: '/home', component: Home,
children: [
// 2. 绝对别名:/foo 渲染 /home/foo
{ path: 'foo', component: Foo, alias: '/foo' },
// 3. 相对别名:解析为 /home/bar-alias
{ path: 'bar', component: Bar, alias: 'bar-alias' },
// 4. 多别名:字符串数组
{ path: 'baz', component: Baz, alias: ['/baz', 'baz-alias'] },
// 5. 空字符串别名:让 /home 直接渲染 default 子路由
{ path: 'default', component: Default, alias: '' },
// 6. 嵌套别名:/home/nested-alias/foo 渲染 /home/nested/foo
{ path: 'nested', component: Nested, alias: 'nested-alias',
children: [
{ path: 'foo', component: NestedFoo }
]
}
]
}
]
})
对照 e2e 测试 test/e2e/specs/route-alias.js 的断言结果,可确认每种形态的实际行为:
/root-alias地址栏保持/root-alias,渲染Root组件;/foo地址栏保持/foo,渲染的是/home/foo的Foo组件;/home/bar-alias渲染/home/bar;/baz与/home/baz-alias都渲染/home/baz的Baz;/home渲染/home/default(空字符串别名实现"默认子路由"效果);/home/nested-alias/foo渲染/home/nested/foo(别名同样能继承子路由)。
3.4 别名的开发期警告与约束
仓库在开发模式下对别名做了防御性检查(src/create-route-map.js#L156-L163):若别名与路径本身完全相同,会触发警告 Found an alias with the same value as the path,并在开发模式下跳过该别名。对应的单元测试见 test/unit/specs/create-map.spec.js#L120-L148,覆盖了单个别名与别名数组两种重复情况。生产环境下该警告被剥离,但重复别名依然不会生效。
四、redirect 与 alias 的类型签名与选择建议
在 docs/api/README.md 的 RouteConfig 类型定义中,两个选项的合法类型为:
redirect?: string | Location | Function // 路径字符串 | 命名路由对象 | 函数
alias?: string | Array<string> // 单个字符串 | 字符串数组
(完整类型定义还可参考 types/router.d.ts。)
选择建议:
- 旧路径需要永久迁移、或希望地址栏展示规范新 URL、或需要"兜底任何未匹配路径"时,使用 redirect(特别是
{ path: '*', redirect: '/' }这类 catch-all); - 同一组件需要同时服务于多个 URL、或想绕过嵌套结构暴露扁平地址、且希望地址栏保持用户输入的原始 URL 时,使用 alias;
- 需要按
query/hash/params动态决定去向时,只能用 redirect 的函数形态; - 若只是想让路由同时响应两个名字,别名是零副作用的选择——它不产生重定向、不追加历史记录、也不影响守卫执行链。
五、小结
重定向与别名是 vue-router 路由配置中最常用的两个"映射工具",二者一字之差、行为迥异:
- redirect:地址栏换 URL、按新地址重匹配、守卫只作用于目标路由,支持字符串 / 命名路由 / 动态函数三种形态,且函数形态能拿到完整的
to路由对象做精细分流; - alias:地址栏保持原 URL、内部用
matchAs换轨到原始路由渲染组件,支持相对 / 绝对 / 多别名 / 嵌套别名,是"同一 UI 多 URL"的最佳答案。
它们的底层实现分别集中在 src/create-matcher.js 的 redirect() / alias() 两个函数与 src/create-route-map.js 的别名注册逻辑中,官方示例 examples/redirect/app.js、examples/route-alias/app.js 与对应的 test/e2e/specs/redirect.js、test/e2e/specs/route-alias.js 端到端测试为每一种用法提供了可复现、可验证的行为依据。