UniApp 页面跳转完全指南：5 种路由方式详解与实战对比

前言

在 UniApp 开发中，页面间的跳转是最常见的操作之一。UniApp 提供了 5 种路由 API，分别对应不同的跳转场景。选错跳转方式轻则体验变差，重则出现"无法返回""Tab 页跳转失败"等让人头疼的 bug。

本文将逐一讲解 5 种跳转方式的原理、适用场景与代码示例，并附上横向对比表，方便日常查阅。

一、uni.navigateTo — 保留式跳转

最常用的跳转方式。跳转到新页面时，当前页面并不会被销毁，而是压入页面栈（page stack），用户可以通过左滑或返回按钮回到上一页。

适用场景：列表页 → 详情页、表单页 → 确认页、所有需要支持返回的场景。

1// 普通跳转
2uni.navigateTo({
3  url: '/pages/detail/index?id=1&type=alarm',
4  success(res) {
5    console.log('跳转成功')
6  },
7  fail(err) {
8    console.log('跳转失败', err)
9  }
10})
11

目标页面通过 onLoad(options) 接收参数：

1onLoad(options) {
2  const id = options.id     // '1'
3  const type = options.type // 'alarm'
4}
5

⚠️ 注意：页面栈最多叠加 10 层，超出后 navigateTo 会静默失败。深层嵌套场景请考虑改用 redirectTo。

二、uni.redirectTo — 替换式跳转

关闭当前页面再打开新页面，当前页面会被销毁。用户在新页面无法通过返回键回到被关闭的那一页。

适用场景：登录成功 → 首页、表单提交完成 → 结果页、中间跳板页。

1// 登录成功后跳转首页，不允许返回登录页
2uni.redirectTo({
3  url: '/pages/home/index'
4})
5

💡 适合"一次性"操作完成后的跳转，比如支付成功页、注册完成页。防止用户按返回键重复触发操作。

三、uni.reLaunch — 全清重置跳转

关闭所有页面后，打开指定页面。页面栈被完全清空，是"最彻底"的跳转方式。

适用场景：退出登录、切换账号、应用重置。

1// 退出登录，清空所有页面历史，跳回登录页
2uni.reLaunch({
3  url: '/pages/login/index'
4})
5
6// reLaunch 也支持跳转到 tabBar 页面（这点与 redirectTo 不同）
7uni.reLaunch({
8  url: '/pages/home/index'
9})
10

四、uni.switchTab — Tab 页跳转

专门用于跳转到 pages.json 中配置了 tabBar 的页面。跳转时会关闭所有非 tabBar 页面。

适用场景：底部 Tab 切换、业务流程结束回到主页。

1// 跳转到首页 Tab（必须在 pages.json tabBar 中配置）
2uni.switchTab({
3  url: '/pages/home/index'
4})
5
6// ❌ 错误：switchTab 不支持 url 传参
7uni.switchTab({
8  url: '/pages/home/index?from=detail' // 参数会被忽略
9})
10

⚠️ 注意：switchTab 的 url 不能带参数。如果需要向 Tab 页传递数据，可以通过 Pinia / 全局变量 / Storage 中转。

五、uni.navigateBack — 返回上级

关闭当前页面，返回上一页或多级页面。delta 指定返回层级数，默认为 1。

适用场景：表单取消、弹窗关闭、跨级返回。

1// 返回上一页
2uni.navigateBack({ delta: 1 })
3
4// 返回两层（跳过中间页）
5uni.navigateBack({ delta: 2 })
6
7// 返回时向上一页传递数据（通过 getCurrentPages）
8const pages = getCurrentPages()
9const prevPage = pages[pages.length - 2]
10prevPage.setData?.({ refreshed: true })
11uni.navigateBack({ delta: 1 })
12

六、横向对比总结

七、实际开发建议

1. 优先 navigateTo，保留返回能力，符合用户操作习惯。
2. 注意页面栈上限，栈深超过 10 层时 navigateTo 会失败，可在关键节点改用 redirectTo。
3. tabBar 页面只能用 switchTab 跳转，用 navigateTo/redirectTo 跳转 tabBar 页会失败或表现异常。
4. switchTab 传参走 Pinia，禁止在 url 上拼参数，改用全局状态管理传递跨页数据。
5. reLaunch 谨慎使用，会清空全部历史，用户无法回退，只适合登出/重置等破坏性操作。

💡 在 Vue 3 + TypeScript 项目中，建议封装一个统一的 router 工具函数，内部根据目标路径是否为 tabBar 自动选择 switchTab 或 navigateTo，减少每次手动判断的心智负担。

如果本文对你有帮助，欢迎点赞收藏～

《UniApp 页面跳转完全指南：5 种路由方式详解与实战对比》 是转载文章，点击查看原文。