TRAE-AI编程
用 uni-app 开发时，页面跳转看似简单，却经常因为用错 API 导致“返回不了”“页面栈爆了”或“参数传不到”。本文先把结论放前面：跳转 API 的核心区别在于是否保留当前页——navigateTo 保留并压栈、redirectTo 关闭当前页再打开、reLaunch 清空栈重开。最容易踩的坑是页面栈最多 10 层、在循环里不停 navigateTo、以及参数只能走 URL 拼接。下面按“先看结论、再讲几个 API 怎么选、最后给排查清单”的顺序讲清楚，帮你在多页流程里一次用对跳转。
一、navigateTo：保留当前页压入栈
uni.navigateTo 是最常用的跳转方式，它的默认行为是“入栈”，也就是说当前页还在，返回时还能回到它。但有一个硬边界：页面栈最多保留 10 层。如果你在循环里不断 navigateTo 而不返回，到第 11 次会直接失效。因此多步流程页面要记得适时返回或替换。基础用法可看 Vue3 基础，理解 uni-app 的页面就是 Vue 组件，再来处理路由会更顺。
uni.navigateTo({
url: '/pages/detail/detail?id=123'
});二、redirectTo 与 reLaunch：关闭还是重开
uni.redirectTo 会关闭当前页再打开目标页，适合“提交后去结果页、不希望用户返回表单”的场景；uni.reLaunch 则清空整个页面栈再打开，常用于登录成功后重置路由。选错会带来体验问题：用 navigateTo 做登录跳转，用户按返回又会回到登录页。需要跨端统一工程化时，小程序开发 的路由思路可作参照，理解不同框架对栈的管理差异。
三、参数传递与接收的坑
uni-app 的跳转参数只能拼在 URL 后面（?id=123），目标页在 onLoad(options) 里接收；如果想传对象，要先 JSON.stringify 再 encodeURIComponent，否则会被截断或丢失。另一个坑是中文参数必须编码，否则部分平台会解析失败。理解前端数据流转可参考 JavaScript 教程，把 URL 编码和对象序列化搞清楚，参数传递的 bug 会少很多。页面骨架结构上，语义化的结构组织思路也有助于多页管理。
四、边界、版本与失败排查清单
页面跳转按下面顺序排查，基本能覆盖绝大多数情况：
- 是否触达页面栈 10 层上限，循环里
navigateTo必须配返回或改用redirectTo； - 是否用错了 API，需要“不返回”就选
redirectTo/reLaunch； - 参数是否走了 URL 编码，对象是否
JSON.stringify后再encodeURIComponent； - 目标页路径是否在
pages.json中注册； - 是否在小程序平台触发了分包加载限制。
性能与兼容层面要注意：页面栈过深会占用更多内存，列表页进入详情页推荐用 navigateTo、详情页返回用系统返回；但连续多步向导应适时 redirectTo 防止栈溢出。版本层面，uni-app 各端（H5、小程序、App）对跳转的限制不完全一致，例如微信小程序对栈层数、分包有硬约束，开发时要按目标端核对。理解这些边界，路由类问题会明显变少，也能和各端方案横向对照。
五、进阶：登录态重置与跨端分包限制
跳转里最容易被忽视的工程场景是登录态变化后的路由重置。用户退出登录或 token 失效时，应当用 reLaunch 清空整个页面栈再进入登录页，而不是 navigateTo，否则返回键会把用户带回到需要登录的隐私页，造成信息泄露风险。把“身份变化 = 清空栈重开”固化成规范，能避免一类常见的安全与体验问题。
另一个跨端坑是分包加载限制。微信小程序对主包与分包的体积、以及分包之间的跳转有硬约束，如果目标页放在分包而当前页在主包，直接 navigateTo 到分包页通常没问题，但跨分包引用组件或反向跳转时要遵守分包规则，否则会白屏或报错。开发时应在 pages.json 里规划好分包结构，并对目标端做真机验证。把这些边界和产品流程对齐，跳转类问题会从“偶发玄学”变成“可预期可控”。
再补充一个和跳转强相关的体验问题：返回刷新。很多列表页跳到详情页编辑后返回，列表数据还是旧的，因为 navigateTo 只是压栈、原页面并未重新拉取。修复做法是在列表页的 onShow 里刷新数据（注意是 onShow 不是 onLoad，因为返回不会重新 onLoad），或利用页面通信通知列表页更新。另一个坑是 redirectTo 之后没有“上一页”可返回，如果用户误操作关闭了结果页会直接退出流程，因此关键路径要提供明确的“返回首页/上一步”按钮，而不是依赖系统返回。把“返回即刷新”和“无栈可退时的兜底”做成规范，跳转体验会稳很多。还有一个多端一致性细节：小程序里 reLaunch 会关闭所有页面，如果跳转前没有把必要状态落地到本地存储或全局状态，临时数据会丢失；涉及 reLaunch 的重置操作要提前保存需保留的数据，再执行跳转。落地时建议先在 pages.json 里配置好页面注册与分包，运行一次跳转命令来检查路由栈与参数是否符合预期，确认不会发生栈溢出或白屏；若运行结果不符合预期，按上面的清单逐项修复，再上真机验证各端表现。最后提醒：跳转 API 的失败大多是静默的（返回 fail 回调而不是抛异常），生产环境一定要在 fail 里做兜底提示与日志，而不是假设跳转一定成功，否则用户会卡在空白页毫无头绪。把失败路径也当成一等公民处理，跳转才真正可靠。
总结
uni-app 页面跳转的核心区别在“是否保留当前页”：navigateTo 压栈保留、redirectTo 关闭当前页、reLaunch 清空栈重开。最容易踩的坑是页面栈 10 层上限、循环里不停 navigateTo、以及参数没做 URL 编码。排查时先按场景选对 API、再确认参数编码与页面注册、最后核对目标端限制。把栈管理和参数传递这两点理清，跳转类问题基本都能一次解决。
常见问题
Q：为什么连续跳转几次之后就跳不动了？
A：因为页面栈最多保留 10 层，超过后 navigateTo 会失效。循环或多步流程里要适时返回，或改用 redirectTo/reLaunch 控制栈深度。
Q：跳转传对象为什么会丢数据？
A：uni-app 参数只能拼在 URL 上，对象要先 JSON.stringify 再 encodeURIComponent，目标页 onLoad 里再解析回来，否则会被截断或转义丢失。
Q：navigateTo 和 redirectTo 怎么选？
A：需要返回上一页用 navigateTo；提交后进入结果页、不希望用户退回原页用 redirectTo；登录后重置整个路由用 reLaunch。按“是否保留当前页”来决策最稳。
