1. 小程序跳转小程序到底在跳什么微信生态里小程序之间的互相跳转早就不是什么新鲜事了。你打开一个外卖小程序点“去支付”跳到微信支付结果页你在一个工具类小程序里点“查看物流”直接跳到另一家快递公司的小程序你在电商小程序里点“联系客服”跳到一个专门做客服系统的小程序。这些场景背后用的都是同一个能力wx.navigateToMiniProgram。这个接口从 2017 年底开始逐步开放到现在已经非常成熟。但成熟不代表简单。我见过太多团队在这个功能上翻车跳过去白屏、跳过去参数丢了、跳过去用户回不来、审核被拒、AppID 写错导致跳转失败。问题五花八门但根子往往就那几个。这篇文章面向的是正在做或准备做小程序互跳的开发者不管你是用原生小程序、UniApp 还是 Taro核心逻辑都一样。我会把wx.navigateToMiniProgram的完整用法、参数设计、AppID 配置、审核要点、常见坑和排查方法全部拆开讲一遍。看完你至少能少走两三个月的弯路。先说清楚一个前提小程序跳转小程序不是你想跳就能跳。微信对这件事有明确的规则约束涉及 AppID 白名单、跳转次数限制、用户授权、审核报备等多个环节。很多人第一次做的时候以为写一行代码就完事了结果发现根本跳不过去就是因为没搞懂这些前置条件。提示本文所有代码示例基于微信原生小程序语法UniApp 和 Taro 的写法会在对应章节单独说明。核心 API 名称和参数结构在各框架下是一致的。2. 跳转前的准备工作AppID、白名单与权限2.1 两个 AppID 的关系必须搞清楚小程序跳转涉及两个角色源小程序当前用户所在的小程序和目标小程序要跳过去的小程序。每个小程序都有自己的 AppID格式是wx开头的一串字符比如wx1234567890abcdef。跳转的时候源小程序需要知道目标小程序的 AppID然后调用wx.navigateToMiniProgram({ appId: 目标AppID })。听起来很简单但这里有个关键点目标小程序必须在源小程序的跳转白名单里。白名单在哪里配登录微信公众平台进入源小程序的后台找到“设置”-“开发设置”-“跳转其他小程序”在里面添加目标小程序的 AppID。最多可以添加 10 个。这个数字很多人不知道等到要跳第 11 个的时候才发现加不进去了。注意白名单配置后需要重新提交代码审核才能生效。如果你在开发工具里测试跳转成功但线上版本跳不过去大概率就是白名单没配或者没重新发版。2.2 跳转次数限制与用户授权微信对小程序跳转有次数限制从同一个源小程序跳转到同一个目标小程序每个用户每天最多跳转 10 次。超过之后会触发fail回调错误信息里会提示达到上限。另外从 2020 年开始微信要求跳转前必须获得用户授权。具体来说第一次跳转时微信会弹出一个确认框问用户是否允许跳转到目标小程序。用户同意后才能跳过去。这个授权是按“源小程序 - 目标小程序”这个组合来记的用户同意过一次之后后续再跳同一个目标就不会再弹了。这个授权机制对转化率有影响。我实测下来首次跳转的流失率大概在 15% 到 25% 之间取决于你弹授权框的时机和文案引导。所以建议在跳转前先做一个自己的确认弹窗告诉用户“即将前往 XX 小程序完成支付”用户点了确认再调wx.navigateToMiniProgram这样授权框弹出来的时候用户心理上更容易接受。2.3 目标小程序的配合要求目标小程序这边也不是完全被动的。如果目标小程序设置了“不允许被跳转”那你怎么配白名单都没用。这个开关在目标小程序的公众平台后台路径是“设置”-“基本设置”-“隐私与安全”-“是否允许被其他小程序跳转”。默认是允许的但有些团队出于安全考虑会关掉。还有一种情况目标小程序如果是个人的可能没有开放跳转能力。企业主体的小程序一般没问题个人主体的小程序在跳转权限上会受限。这个在选目标小程序的时候就要确认清楚。3. wx.navigateToMiniProgram 参数详解与实操3.1 完整参数列表先看官方文档里的参数定义我把它拆开逐条解释wx.navigateToMiniProgram({ appId: wx1234567890abcdef, // 目标小程序 AppID必填 path: pages/index/index?id1, // 目标小程序页面路径可选 extraData: { // 传递给目标小程序的数据可选 from: sourceApp, orderId: 12345 }, envVersion: release, // 目标小程序版本可选 success(res) { // 跳转成功回调 console.log(跳转成功, res) }, fail(err) { // 跳转失败回调 console.error(跳转失败, err) }, complete() { // 无论成功失败都会执行 } })appId是唯一必填项其他都是可选的。但实际业务里path和extraData几乎一定会用到因为你不光要跳过去还要告诉对方“我是谁、我要干什么”。3.2 path 参数的写法与编码问题path指定目标小程序打开哪个页面格式是页面路径?参数1值1参数2值2。页面路径不能以/开头比如pages/detail/detail是对的/pages/detail/detail会报错。参数值如果包含特殊字符比如中文、空格、、必须用encodeURIComponent编码。我踩过一次坑传了一个带中文的参数开发工具里正常真机上直接白屏。后来发现是中文没编码目标小程序解析参数时出了问题。const name encodeURIComponent(张三) wx.navigateToMiniProgram({ appId: wx1234567890abcdef, path: pages/user/user?name${name}id100, success() { console.log(ok) } })目标小程序在onLoad里接收参数时微信会自动做一次解码所以你在options.name里拿到的就是原始的中文。但如果你在 path 里手动编码了两次那就会出问题。记住编码一次就够了。3.3 extraData 的使用与限制extraData是一个对象用来传递结构化数据。目标小程序在App.onLaunch或App.onShow里可以通过options.referrerInfo.extraData拿到。// 源小程序 wx.navigateToMiniProgram({ appId: wx1234567890abcdef, path: pages/index/index, extraData: { source: mall, userId: u_12345, timestamp: Date.now() } }) // 目标小程序 App.js App({ onLaunch(options) { if (options.referrerInfo options.referrerInfo.extraData) { const { source, userId, timestamp } options.referrerInfo.extraData console.log(来自, source, 的用户, userId) } }, onShow(options) { // 从后台切回来也会触发注意去重 if (options.referrerInfo options.referrerInfo.extraData) { // 处理逻辑 } } })这里有个容易忽略的点extraData只在跳转发生时传递一次。如果用户跳过去之后把目标小程序切到后台再切回来onShow里的options.referrerInfo可能还在也可能不在取决于微信版本和系统。所以不要依赖onShow里的extraData做关键业务逻辑重要数据还是走path参数或者目标小程序自己调接口查。另外extraData的大小有限制官方没有明确说多少但实测超过 1KB 就可能被截断。传大对象的时候要小心。3.4 envVersion 的选择envVersion有三个值release正式版、trial体验版、develop开发版。默认是release。这个参数在开发阶段很有用。比如你在开发源小程序想跳到目标小程序的体验版测试就设envVersion: trial。但要注意只有目标小程序的开发者或体验成员才能跳到体验版普通用户跳体验版会失败。线上环境一定要用release否则用户跳过去会提示“小程序未发布”或者直接白屏。4. 完整实操流程从零实现一次跳转4.1 第一步配置源小程序白名单登录源小程序的微信公众平台进入“设置”-“开发设置”-“跳转其他小程序”点击“添加”输入目标小程序的 AppID保存。然后重新提交代码审核审核通过后发布。这一步不做线上跳转必失败。4.2 第二步编写跳转代码在源小程序的页面里找一个按钮或者触发点绑定跳转事件// pages/index/index.js Page({ data: { targetAppId: wx1234567890abcdef }, onJumpTap() { const that this wx.showModal({ title: 即将前往, content: 将打开「目标小程序」完成后续操作, success(res) { if (res.confirm) { that.doJump() } } }) }, doJump() { wx.navigateToMiniProgram({ appId: this.data.targetAppId, path: pages/detail/detail?fromsourceid100, extraData: { source: sourceApp, timestamp: Date.now() }, envVersion: release, success(res) { console.log(跳转成功, res) // 可以在这里埋点 }, fail(err) { console.error(跳转失败, err) wx.showToast({ title: 跳转失败请重试, icon: none }) // 根据 err.errMsg 做具体处理 } }) } })4.3 第三步目标小程序接收参数目标小程序在App.js和对应页面的onLoad里接收// 目标小程序 App.js App({ onLaunch(options) { this.handleReferrer(options) }, onShow(options) { this.handleReferrer(options) }, handleReferrer(options) { if (options.referrerInfo options.referrerInfo.appId) { console.log(来自小程序, options.referrerInfo.appId) if (options.referrerInfo.extraData) { console.log(额外数据, options.referrerInfo.extraData) } } } }) // 目标小程序 pages/detail/detail.js Page({ onLoad(options) { console.log(页面参数, options) // options 里包含 path 中传递的 from 和 id const { from, id } options if (from source) { // 根据来源做不同处理 } } })4.4 第四步处理跳转失败fail回调里的err.errMsg是排查问题的关键。常见的错误信息我整理成了表格errMsg 关键词含义解决办法fail appId is invalidAppID 格式错误或不存在检查 AppID 是否拼写正确fail not in jump list目标小程序不在白名单去公众平台添加白名单并重新发版fail permission denied用户拒绝了授权引导用户重新点击并同意fail limit exceeded当天跳转次数超限提示用户明天再试fail target app not released目标小程序未发布确认目标小程序已上线fail system error微信侧系统错误重试或联系微信客服提示fail回调里不要只写console.log一定要给用户一个明确的反馈。我见过很多小程序跳转失败后什么都不提示用户一脸懵。5. UniApp 和 Taro 下的跳转写法5.1 UniApp 写法UniApp 对wx.navigateToMiniProgram做了封装但本质上还是调微信原生 API。在 UniApp 里可以这样写// UniApp 页面方法 methods: { jumpToMiniProgram() { // #ifdef MP-WEIXIN wx.navigateToMiniProgram({ appId: wx1234567890abcdef, path: pages/index/index?id1, extraData: { from: uniapp }, success() { console.log(跳转成功) }, fail(err) { console.error(跳转失败, err) } }) // #endif // #ifndef MP-WEIXIN uni.showToast({ title: 仅微信小程序支持, icon: none }) // #endif } }注意条件编译。UniApp 一套代码可能编译到多个平台但wx.navigateToMiniProgram只在微信小程序里存在。如果不加条件编译编译到 H5 或 App 时会报错。5.2 Taro 写法Taro 里可以直接用Taro.navigateToMiniProgramimport Taro from tarojs/taro const jump () { Taro.navigateToMiniProgram({ appId: wx1234567890abcdef, path: pages/index/index, extraData: { from: taro }, success: () console.log(ok), fail: (err) console.error(err) }) }Taro 的 API 签名和微信原生基本一致参数名也一样。唯一要注意的是 Taro 版本3.x 和 2.x 在类型定义上有些差异但运行时行为是一样的。6. 常见问题与排查技巧实录6.1 跳转成功但目标小程序白屏这是最常见的问题之一。原因通常有三个目标小程序的path写错了、目标小程序那个页面需要登录态但没拿到、目标小程序页面本身有 bug。排查方法先在微信开发者工具里直接打开目标小程序的编译模式指定同样的 path 和参数看能不能正常渲染。如果开发者工具里正常但真机白屏检查一下path里的参数是否编码正确以及目标小程序是否对来源做了限制。6.2 参数丢失或乱码前面提过中文和特殊字符必须encodeURIComponent。还有一种情况参数值里带了比如nameab微信会把当成参数分隔符导致name只拿到a。解决办法还是编码。// 错误写法 path: pages/index/index?nameab // 正确写法 path: pages/index/index?name${encodeURIComponent(ab)}6.3 用户跳过去之后回不来小程序跳转是单向的。从 A 跳到 B 之后用户按左上角返回会回到微信的聊天列表或者发现页而不是回到 A。如果业务需要用户跳过去操作完再回到 A目标小程序需要自己调wx.navigateBackMiniProgram跳回来。// 目标小程序里返回源小程序 wx.navigateBackMiniProgram({ extraData: { result: success, orderId: 12345 }, success() { console.log(返回成功) } })源小程序在App.onShow里通过options.referrerInfo.extraData接收返回数据。这个闭环设计在支付、授权等场景里非常常用。6.4 审核被拒的常见原因小程序跳转功能在提审时微信审核员会重点关注跳转的目的是否合理、目标小程序是否合规、是否存在诱导跳转。我总结了几条避坑经验跳转按钮的文案要明确不能写“点击有惊喜”这种模糊表述跳转目标必须是白名单里的 AppID不能动态切换不能强制跳转必须给用户选择权跳转后的目标小程序内容要和源小程序的描述一致6.5 常见问题速查表问题现象可能原因排查方向开发工具正常真机失败白名单未生效确认已重新发版首次跳转弹授权框用户拒绝后无法再跳授权被拒引导用户删除小程序重进跳转后目标小程序收不到 extraData目标小程序未在 onLaunch/onShow 处理检查 referrerInfo 读取逻辑跳转次数超限单用户单日超 10 次做次数提示和降级方案iOS 正常Android 失败微信版本过低提示用户升级微信7. 一些实操心得和进阶玩法做小程序跳转这几年我最大的体会是不要把它当成一个纯技术问题。技术实现可能半小时就搞定了但白名单配置、审核沟通、目标小程序配合、用户授权引导这些才是真正花时间的地方。有个技巧我一直在用在跳转前先调一次wx.getSetting或者自己维护一个本地标记判断用户是否已经授权过跳转。如果授权过直接跳如果没授权过先弹自己的引导弹窗提高授权通过率。另外extraData虽然方便但不要传敏感信息。它是明文传递的用户抓包能看到。订单号、用户 ID 这类不敏感的数据可以传手机号、身份证号绝对不要放进去。还有一个进阶玩法利用wx.navigateToMiniProgram做小程序矩阵的流量分发。比如你有一组小程序主小程序负责引流子小程序负责不同业务通过跳转把用户导到对应的子小程序。这种架构下白名单的 10 个名额要提前规划好别等到不够用了再删。最后分享一个排查技巧如果跳转失败但errMsg看不明白可以在fail回调里把完整的err对象JSON.stringify后打到日志里然后去微信开发者工具的“调试器”-“Console”里看。有些错误信息在errMsg里被截断了完整对象里才有细节。