一、uni-app 路由跳转方式汇总跳转方式 (API)当前页面处理页面栈变化能否传参典型实际开发场景uni.navigateTo保留不销毁压入栈中叠加1能URL拼接列表页跳转到详情页最常用uni.redirectTo关闭销毁当前页面替换±0能URL拼接登录成功跳首页、表单提交成功跳结果页uni.reLaunch全关销毁所有历史页面清空重置能URL拼接退出登录、切换账号、应用强制重置uni.switchTab关闭销毁所有非 Tab 页面重置为 Tab 页不能不支持 URL 传参底部 Tab 栏切换、业务流程结束回主页uni.navigateBack关闭销毁当前页面回退-N不能需间接传值自定义返回按钮、跨级返回上一页二、navigateTo作用保留当前页面跳转到应用内的某个非 tabBar 页面。跳转后新页面会压入页面栈用户可以通过左上角的返回按钮或调用uni.navigateBack回到原页面。2. 用法基础跳转uni.navigateTo({url:/pages/detail/detail?id123nametest});目标页面接收参数Vue3 setup 语法糖script setup import { onLoad } from dcloudio/uni-app; onLoad((options) { console.log(options.id); // 123 console.log(options.name); // test }); /script页面间通信events 事件监听2.8.9 支持// 发起跳转的页面uni.navigateTo({url:/pages/detail/detail,events:{// 监听目标页面传回的数据acceptDataFromOpenedPage:function(data){console.log(data);}},success:function(res){// 向目标页面发送数据res.eventChannel.emit(acceptDataFromOpenerPage,{data:来自上一页});}});3. 避坑指南页面栈溢出10层限制现象连续跳转超过 10 次后报错navigateTo:fail:page limit exceeded:10或静默失败。原因uni-app 限制页面栈最大深度为 10 层。解决跳转前通过getCurrentPages()检查栈深度若接近 10 层改用uni.redirectTo替换当前页面或uni.navigateBack释放栈空间后再跳转。无法跳转 TabBar 页面现象使用 navigateTo 跳转底部导航栏页面时页面没有反应或报错。解决跳转 TabBar 页面必须使用uni.switchTab。URL 参数长度限制与乱码现象传递复杂的 JSON 对象或超长字符串时参数丢失或接收端乱码。解决URL 有长度限制复杂数据应改用全局状态管理如 Pinia或本地缓存uni.setStorageSync若必须通过 URL 传递特殊字符发送端需使用encodeURIComponent编码接收端使用decodeURIComponent解码。H5 端微信浏览器兼容问题现象在微信公众号 H5 中使用 navigateTo 跳转后调用微信 JSSDK如获取定位在 iOS 上签名校验失败。原因iOS 微信浏览器在 navigateTo 跳转后获取的当前页面链接可能仍是列表页链接导致签名比对失败。解决涉及 JSSDK 签名的页面尽量避免深层 navigateTo或在 iOS 端做特殊的路由刷新处理。三、redirectTo作用关闭当前页面跳转到应用内的某个非 tabBar 页面。新页面会替换当前页面在页面栈中的位置用户无法通过返回按钮回到被关闭的当前页面。2. 用法基础跳转uni.redirectTo({url:/pages/result/result?statussuccess});目标页面接收参数Vue3 setupscript setup import { onLoad } from dcloudio/uni-app; onLoad((options) { console.log(options.status); // success }); /script3. 避坑指南坑点一无法跳转 TabBar 页面现象跳转底部导航栏页面时静默失败或报错。解决跳转 TabBar 页面必须使用uni.switchTab。坑点二误用导致用户无法回退现象用户在详情页点击返回按钮直接退出了小程序或回到了很远的页面。原因redirectTo 会销毁当前页面如果用在列表页跳详情页的场景用户看完详情就无法回到列表了。解决严格区分场景只有“不需要返回当前页”如登录成功、表单提交成功时才使用 redirectTo。坑点三页面栈深度不增加现象连续使用 redirectTo 跳转多次后调用uni.navigateBack发现回退的层级不对。原因redirectTo 是替换操作±0不会增加页面栈深度。解决需要精确控制返回层级时使用getCurrentPages()动态计算 delta 值。四、reLaunch作用关闭所有已打开的页面打开到应用内的某个页面。相当于对应用的导航状态进行了一次“硬重启”目标页面成为新的页面栈根页面。2. 用法基础跳转uni.reLaunch({url:/pages/index/index});带参数跳转非 TabBar 页面uni.reLaunch({url:/pages/detail/detail?id123_tDate.now()});目标页面接收参数Vue3 setupscript setup import { onLoad } from dcloudio/uni-app; onLoad((options) { console.log(options.id); // 123 }); /script3. 避坑指南坑点一TabBar 页面不能带参数现象跳转 TabBar 页面时 URL 带了?keyvalue参数被忽略或跳转静默失败。解决跳转 TabBar 页面时URL 必须完全匹配 pages.json 中的配置路径不能携带任何 query 参数。需要传参请使用 Pinia / Storage / 事件总线。坑点二缓存导致“看起来没刷新”现象调用 reLaunch 跳转到当前页面但页面数据没有更新。原因路由复用机制可能导致页面实例被缓存。解决在 URL 后拼接时间戳参数如?_tDate.now()强制触发页面重建。坑点三在下拉刷新回调中使用导致动画卡死现象在 onPullDownRefresh 中调用 reLaunch下拉刷新动画一直转圈不消失。解决不要在 onPullDownRefresh 中混用uni.reLaunch。如果确实需要重载应先调用uni.stopPullDownRefresh()停止动画或使用数据重拉方案替代。坑点四重复点击导致 locked 错误现象快速连续点击按钮控制台报错reLaunch:fail pages/index/index locked。原因第一次 reLaunch 正在执行时再次调用会被锁定。解决添加防重复点击机制导航锁确保跳转操作不会连续触发。坑点五生命周期触发异常现象跳转到 TabBar 页面后onShow / onLoad 没有触发导致定时器或数据请求未执行。原因TabBar 页面在应用启动时已创建reLaunch 可能只触发 onShow 而不触发 onLoad具体表现因平台而异。解决将数据初始化逻辑放在 onShow 中或改用 switchTab 事件通知的方式。坑点六H5 端浏览器历史记录无法清空现象H5 端调用 reLaunch 后点击浏览器返回按钮仍能回到之前的页面。原因reLaunch 只清空了 uni-app 内部的页面栈无法清除浏览器自身的历史记录。解决H5 端如需完全控制浏览器历史需配合history.replaceState或location.replace处理。坑点七部分安卓低端机白屏/闪退现象调用 reLaunch 后页面白屏或应用闪退无报错信息。原因页面栈被瞬间全部销毁重建低端机性能不足或存在 onUnload 中的异步操作冲突。解决确保所有页面的 onUnload 中不要执行耗时的异步操作如在 onUnload 中调用 navigateBack条件允许时优先使用“数据重拉 手动 reset”方案替代 reLaunch。坑点八不支持过渡动画配置现象设置了 animationType 参数但跳转无动画效果。解决reLaunch 是原子操作不支持 animationType 等过渡配置跳转过程无动画。如需动画效果请改用uni.navigateTo或uni.redirectTo。五、switchTab1. 作用跳转到 tabBar 页面并关闭其他所有非 tabBar 页面。它专门用于底部导航栏TabBar的切换。2. 用法基础跳转uni.switchTab({url:/pages/index/index});目标页面接收数据Vue3 setup由于 switchTab 不支持 URL 传参通常使用全局状态管理如 Pinia或本地缓存Storage来传递数据// 跳转前存储数据uni.setStorageSync(tabData,{keyword:test});uni.switchTab({url:/pages/index/index});// 目标页面获取数据 script setup import { onShow } from dcloudio/uni-app; onShow(() { const data uni.getStorageSync(tabData); console.log(data); // { keyword: test } }); /script3. 避坑指南坑点一不支持 URL 传参现象URL 后面拼接了?id123但目标页面的 onLoad 中拿不到参数。原因TabBar 页面首次加载后会被缓存后续切换只触发 onShow 而不触发 onLoad因此无法接收 URL 参数。解决必须使用 Pinia、Vuex、uni.setStorageSync或全局变量进行数据传递。坑点二路径必须完全匹配现象跳转静默失败控制台报 warning。原因url 必须是 pages.json 中tabBar.list里配置的真实路径不能携带任何 query 参数也不能加.vue后缀。解决检查url是否与pages.json中tabBar.list配置的页面路径完全一致不要添加额外参数或文件后缀。坑点三App 端偶发闪白/闪退现象从深层页面调用 switchTab 跳回首页时页面快速闪动一下白色或先退回手机桌面再显示首页。原因这是 uni-app 在部分 App 端的已知渲染 Bug通常与同时销毁大量非 Tab 页面有关。解决可尝试使用uni.reLaunch替代或延迟跳转如setTimeout100ms确保 HBuilderX 升级到较新的正式版本。坑点四H5 端路由初始化问题现象在应用启动初期如 onLaunch 中立即调用 switchTabH5 端可能报错Cannot read properties of undefined (reading replace)。原因应用启动初期 uni-app 的路由对象尚未完成初始化此时调用 switchTab 会访问到尚未就绪的路由实例。解决确保在 onReady 生命周期之后再调用 switchTab或使用 setTimeout 延迟执行。六、navigateBack1. 作用关闭当前页面返回上一页面或多级页面。它是uni.navigateTo等 API 的逆操作。2. 用法返回上一页uni.navigateBack();返回指定层级// 返回上上个页面uni.navigateBack({delta:2});3. 避坑指南坑点一H5 端刷新后失效静默失败现象在 H5 端刷新页面后点击返回按钮毫无反应。原因H5 刷新会清空 uni-app 运行时维护的虚拟页面栈导致getCurrentPages()仅剩当前页navigateBack 找不到上一页。解决封装安全返回方法当页面栈长度 1时降级使用浏览器原生能力history.back()或history.go(-delta)。坑点二在 onBackPress 中死循环现象在 onBackPress 生命周期中调用uni.navigateBack()导致页面卡死或无限触发返回。原因uni.navigateBack()本身也会触发 onBackPress。解决在 onBackPress 中判断来源options.from当来源为navigateBack时直接return false放行避免死循环。坑点三拦截异步操作导致提前返回现象在 onBackPress 中弹出确认框showModal但用户还没点击确定页面就已经退回去了。原因showModal 是异步的而 onBackPress 是同步执行的函数执行完就放行了。解决在 onBackPress 中先return true阻止默认返回然后在弹窗的回调中再手动调用uni.navigateBack()。坑点四Web-view 冲突现象在 App 中使用 web-view 加载 H5点击返回时只退回了 H5 的上一页没有退出 Web-view 组件。原因App 端的返回键默认优先触发 Web-view 内部 H5 的路由返回。解决在 Web-view 所在页面的 onBackPress 中通过 plus API 获取 Web-view 对象判断 H5 是否还有历史记录若无则手动关闭 Web-view 并调用uni.navigateBack()。坑点五delta 超出页面栈深度现象传入的 delta 值大于当前页面栈层数返回行为不符合预期。原因navigateBack的 delta 参数表示要回退的层数超出可回退范围时不同平台会采用兜底策略如直接回到首页与预期可能不一致。解决跳转前使用getCurrentPages()获取当前页面栈长度动态计算安全的 delta 值如果 delta 大于现有页面数系统会自动返回到首页。
