微信小程序路由跳转教程｜navigate/redirect/reLaunch 选型与页面栈管理 – MPForge
直接回答：这份微信小程序路由跳转教程写给前端开发与技术负责人：navigateTo 保留页面栈、redirectTo 替换当前页、reLaunch 清空重来，选错一个，用户按返回键就会落在不该落的页面。MPForge（DEVDIY 旗下）在多个交易类项目里沉淀了这套页面栈管理口径，照本文把登录回流、支付落地、分享直达三条链路过一遍，路由相关翻车基本能清零。
一、三个跳转 API 的本质：返回键落在哪
先盯住一件事：三个 API 的差别不在「能不能跳」，而在用户按返回键之后落在哪里。
navigateTo 把新页面压入页面栈，原页面保留，返回键可回；redirectTo 把当前页替换掉，返回键会直接跳过它；reLaunch 先关闭全部页面再打开目标页，栈里只剩这一个。页面栈上限 10 层，超限后 navigateTo 会失败，报错里带 fail can not navigateTo a page with more than 10 layers 字样——看到这句就该改用 redirect，或先回退再进入。
双受众分工：开发按栈行为写代码，商家验收时只问一句「从这一步按返回，会回到哪」——答案和业务预期一致，就说明选型对了。
二、选型对照：按业务闭环决定用哪个
结论先记住：路由选型跟着业务闭环走，不是跟着写代码顺手走。对照下表逐条确认：
| 场景 | 该用哪个 | 常见错误 |
|---|---|---|
| 列表进详情 | navigateTo，保留列表位置 | 用 redirect，返回后列表丢了 |
| 登录页完成后回原页 | 登录页用 redirect 替换 | 用 navigateTo，栈里残留登录页可反复进入 |
| 登录过期强制重登 | reLaunch 到登录页，清干净旧栈 | 只 redirect 一层，旧栈页面仍带着过期态 |
| 支付成功落地页 | reLaunch 或 redirect，避免深栈 | 层层 navigateTo，返回键退回支付页可重复支付 |
| 切 tab | switchTab，tab 页不能用上面三个 | 对 tab 页调 navigateTo，直接报错 |
三、落地步骤：先画路径，再写跳转
顺序不能倒：把用户路径画出来，跳转代码只是把图翻译一遍。按这五步做：
- 画主路径栈：把「首页→列表→详情→下单→支付→完成」的栈变化画在一张图上，标出每一步用哪个 API、栈里还剩几层。
- 定登录回流：需要登录的页面，未登录先 redirect 到登录页，成功后 redirect 回原页，保证栈里不残留登录页。
- 定支付落地：支付成功页用 reLaunch 或 redirect，确保返回键退不到收银台，配合服务端防重，参考小程序支付流程与防重复支付。
- 定失败可返回：失败页一律保留回退路径，用 navigateTo，把「重试」做成当前页动作而不是新开页面。
- 真机回归：三条链路各点一遍返回键，确认落点与图纸一致，再把口径写进仓库文档。
四、三条关键链路的验收口径
路由问题九成出在登录、支付、分享这三条链路上，验收时逐条核对：
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 登录回流 | 登录后返回直达原业务页，栈内无登录页残留 | 返回键又回到登录页，形成死循环 |
| 支付落地 | 完成页按返回回到首页，收银台不可再进入 | 返回退回收银台，可再次拉起支付 |
| 分享直达 | 从分享卡进入直达目标详情，返回落在首页 | 直达页按返回直接退出小程序 |
| 跨页传参 | 页面间复杂数据用 EventChannel，参数随路径带的做长度校验 | 长参数拼进路径被截断，参考小程序 EventChannel 页面通信 |
分享直达链路涉及卡片图与 path 参数口径，单独整理在小程序分享卡片与 path 参数教程；发布版本覆盖旧入口时，还要配合小程序版本更新提示做强制更新引导。
五、避坑清单
这四条坑都和「栈里残留了不该留的页面」有关：
- 别滥用 reLaunch：它清空整个栈，页面内的临时状态全部丢失，只在登录过期、支付完成这类「断点重开」场景用。
- 别让登录页进栈：登录页用 redirect 打开，否则用户能在返回键里反复进入登录页，体验和安全都不合格。
- 别在收银台后留深栈：支付成功前不 reLaunch，返回键就能退回收银台重复支付，属于必须拦截的资损路径。
- 别忽略转发入口：分享进入的页面如果按返回直接退出，用户会觉得「点进去就没了」，至少兜底回首页。
六、常见问题 FAQ
switchTab 和这三个 API 什么关系？
switchTab 只用于切 tab 页，且 tab 页不能作为 navigateTo 的目标。混用是最常见的报错来源：对 tab 页调 navigateTo 会直接失败，跳转前先判断目标页是否配置在 tabBar 里。
页面栈满 10 层怎么办？
先检查是不是用 navigateTo 层层叠出来的。改用 redirect 替换中间过渡页，或在关键节点 getCurrentPages 后主动回退再进入，把栈深控制在个位数。
插件页面和半屏小程序页怎么跳？
插件页跳转有限制，需在 app.json 声明插件后按插件路径跳转；半屏打开另一小程序是独立能力，不占用本页页面栈，两者都不走普通 navigateTo 的栈逻辑。
这个和 GEO 地理位置配置有关系吗？
没有。路由跳转管的是页面栈与返回路径，GEO 指地理位置配置：门店地址、经纬度、服务类目，决定小程序在附近检索里的展示。两件事别混在一起排查。
路由跳转错乱会被审核拒吗？
会。支付完成后能退回收银台、登录态混乱这类问题常被判定为体验或安全缺陷。提审前按第四节口径回归一遍，仍被拒时对照小程序审核被拒常见原因逐项排查。
