微信小程序生態(tài)里從小程序 A 跳到小程序 B 這個(gè)需求看起來只是調(diào)一個(gè) API 的事但真正落地過的開發(fā)者都知道坑遠(yuǎn)比想象中多。我第一次做這個(gè)功能是在一個(gè)電商導(dǎo)購項(xiàng)目里主小程序需要跳轉(zhuǎn)到品牌方的獨(dú)立小程序完成下單當(dāng)時(shí)以為wx.navigateToMiniProgram一行代碼就搞定了結(jié)果在真機(jī)上測了整整兩天才跑通——有跳不過去的有跳過去回不來的還有跳過去之后參數(shù)丟了的。這篇文章就把這套流程從頭到尾拆一遍包括 AppID 怎么配、參數(shù)怎么傳、回跳怎么接、審核怎么過以及那些官方文檔里不會(huì)明說的邊界條件。不管你是剛接觸小程序跳轉(zhuǎn)的新手還是已經(jīng)踩過幾次坑的老手應(yīng)該都能從里面找到點(diǎn)有用的東西。1. 跳轉(zhuǎn)前必須搞清楚的三個(gè)前置條件很多人拿到需求就開始寫代碼結(jié)果調(diào)了半天 API 一直報(bào)錯(cuò)回頭才發(fā)現(xiàn)是前置條件沒滿足。小程序跳轉(zhuǎn)不是你想跳就能跳的微信在這件事上設(shè)了三道門檻任何一道沒過wx.navigateToMiniProgram都會(huì)直接失敗。1.1 目標(biāo)小程序的 AppID 必須提前聲明這是最容易被忽略的一條。從基礎(chǔ)庫 2.0.7 開始你需要在當(dāng)前小程序的app.json里配置一個(gè)navigateToMiniProgramAppIdList字段把你要跳轉(zhuǎn)過去的目標(biāo)小程序 AppID 列進(jìn)去。注意這個(gè)列表最多只能填 10 個(gè)超了會(huì)報(bào)錯(cuò)。{ navigateToMiniProgramAppIdList: [ wx240a4a764023c444, wx3d347910697206ad ] }為什么要有這個(gè)限制我的理解是微信在做一層白名單管控防止小程序之間隨意互相導(dǎo)流。你聲明了哪些 AppID就只能跳哪些沒聲明的調(diào) API 會(huì)直接拋fail appId not in navigateToMiniProgramAppIdList這個(gè)錯(cuò)誤。這里有個(gè)實(shí)操細(xì)節(jié)這個(gè)列表是靜態(tài)配置改一次就要重新提交審核發(fā)版。所以如果你做的是那種目標(biāo)小程序會(huì)動(dòng)態(tài)變化的業(yè)務(wù)比如導(dǎo)購平臺(tái)對接多個(gè)品牌這個(gè)方案就不太適用了。我當(dāng)時(shí)的做法是把品牌方小程序收斂到固定的幾個(gè)超過 10 個(gè)的就走 H5 中轉(zhuǎn)頁兜底。提示navigateToMiniProgramAppIdList的配置在開發(fā)者工具里可能不會(huì)嚴(yán)格校驗(yàn)但真機(jī)上一定會(huì)校驗(yàn)。別只在模擬器里測一定要真機(jī)驗(yàn)證。1.2 目標(biāo)小程序必須與當(dāng)前小程序存在關(guān)聯(lián)關(guān)系光配了 AppID 還不夠。微信要求兩個(gè)小程序之間必須有關(guān)聯(lián)關(guān)系具體來說就是目標(biāo)小程序的管理員需要在小程序管理后臺(tái) - 設(shè)置 - 關(guān)聯(lián)小程序里把你的小程序添加為關(guān)聯(lián)方或者反過來你關(guān)聯(lián)它。這個(gè)關(guān)聯(lián)關(guān)系是雙向確認(rèn)的單方面配了 AppID 但沒建立關(guān)聯(lián)跳轉(zhuǎn)照樣失敗。這一步經(jīng)?？ㄔ跍贤ㄉ?。如果你是甲方主小程序要跳乙方的小程序得讓乙方的運(yùn)營去后臺(tái)操作關(guān)聯(lián)。我遇到過對方運(yùn)營完全不知道這個(gè)功能在哪的情況最后是我截圖一步步教他點(diǎn)的。所以項(xiàng)目排期的時(shí)候這個(gè)關(guān)聯(lián)確認(rèn)的時(shí)間一定要預(yù)留出來別等到發(fā)版前一天才發(fā)現(xiàn)關(guān)聯(lián)沒做。1.3 用戶授權(quán)與跳轉(zhuǎn)確認(rèn)彈窗從某個(gè)基礎(chǔ)庫版本開始首次跳轉(zhuǎn)時(shí)微信會(huì)彈一個(gè)確認(rèn)框問用戶是否允許打開其他小程序。這個(gè)彈窗是系統(tǒng)級的你沒法繞過也沒法自定義文案。用戶點(diǎn)了允許之后后續(xù)再跳同一個(gè)目標(biāo)小程序就不會(huì)再彈了除非用戶清除了授權(quán)記錄。這個(gè)彈窗對轉(zhuǎn)化率是有影響的。我實(shí)測過一組數(shù)據(jù)加了跳轉(zhuǎn)確認(rèn)之后從點(diǎn)擊到真正進(jìn)入目標(biāo)小程序的轉(zhuǎn)化率大概掉了 15% 左右。所以如果你的業(yè)務(wù)強(qiáng)依賴跳轉(zhuǎn)轉(zhuǎn)化建議在點(diǎn)擊按鈕之前先做一層引導(dǎo)告訴用戶即將跳轉(zhuǎn)到 XX 小程序完成操作讓用戶有心理預(yù)期減少彈窗帶來的突兀感。2. wx.navigateToMiniProgram 的參數(shù)細(xì)節(jié)與傳參實(shí)戰(zhàn)前置條件搞定之后就到了核心的 API 調(diào)用環(huán)節(jié)。這個(gè) API 的參數(shù)看起來不多但每一個(gè)都有講究尤其是path和extraData這兩個(gè)用不好就會(huì)出問題。2.1 核心參數(shù)逐個(gè)拆解先看完整的調(diào)用簽名wx.navigateToMiniProgram({ appId: wx240a4a764023c444, path: subpackages/activity/pages/detail/index?id123, extraData: { from: mainApp, token: abc123 }, envVersion: release, success(res) { console.log(跳轉(zhuǎn)成功, res) }, fail(err) { console.error(跳轉(zhuǎn)失敗, err) } })appId不用多說就是目標(biāo)小程序的 AppID必須和app.json里聲明的一致。path是目標(biāo)小程序的頁面路徑這里有個(gè)大坑path 不能以斜杠開頭。很多人習(xí)慣性寫成/pages/index/index結(jié)果跳過去打開的是目標(biāo)小程序的首頁而不是指定頁面。正確的寫法是pages/index/index不帶前導(dǎo)斜杠。envVersion指定打開目標(biāo)小程序的版本可選值有develop開發(fā)版、trial體驗(yàn)版、release正式版默認(rèn)是release。這個(gè)參數(shù)在聯(lián)調(diào)階段特別有用你可以讓目標(biāo)小程序先發(fā)個(gè)體驗(yàn)版然后指定envVersion: trial來測試不用等正式版發(fā)版。extraData是用來傳參的目標(biāo)小程序在App.onLaunch或App.onShow里可以通過options.referrerInfo.extraData拿到。注意這個(gè)參數(shù)只支持可序列化的對象函數(shù)、Date 對象這些傳不過去。2.2 path 傳參 vs extraData 傳參怎么選這是我在項(xiàng)目里糾結(jié)過的一個(gè)問題。兩種傳參方式都能把數(shù)據(jù)帶到目標(biāo)小程序但適用場景不一樣。傳參方式數(shù)據(jù)位置長度限制適用場景path 拼接options.query受 URL 長度限制建議 1024 字符內(nèi)簡單參數(shù)、需要被目標(biāo)小程序頁面直接讀取extraDataoptions.referrerInfo.extraData官方未明確實(shí)測幾 KB 沒問題復(fù)雜對象、敏感信息、不想暴露在 URL 里的數(shù)據(jù)我的經(jīng)驗(yàn)是如果參數(shù)需要目標(biāo)小程序的某個(gè)具體頁面直接使用比如商品 ID走 path 拼接更直接如果是全局性的上下文信息比如來源標(biāo)識、用戶 token走 extraData 更合適。兩者可以同時(shí)用目標(biāo)小程序那邊分別從options.query和options.referrerInfo.extraData取就行。有個(gè)細(xì)節(jié)要注意extraData里的數(shù)據(jù)在目標(biāo)小程序的onShow里也能拿到但只在首次打開時(shí)有效。如果用戶從目標(biāo)小程序返回后再跳一次referrerInfo會(huì)更新為最新一次的數(shù)據(jù)。2.3 目標(biāo)小程序如何接收參數(shù)目標(biāo)小程序這邊的接收邏輯很多人寫得不完整。正確的做法是在App.onLaunch和App.onShow里都處理App({ onLaunch(options) { this.handleReferrer(options) }, onShow(options) { this.handleReferrer(options) }, handleReferrer(options) { const { referrerInfo } options if (referrerInfo referrerInfo.appId) { const { extraData } referrerInfo // 存到全局或緩存供頁面使用 this.globalData.fromApp referrerInfo.appId this.globalData.extraData extraData || {} } }, globalData: { fromApp: , extraData: {} } })為什么要兩個(gè)生命周期都寫因?yàn)樾〕绦蚩赡苁抢鋯?dòng)onLaunch觸發(fā)也可能是熱啟動(dòng)只觸發(fā)onShow。如果只寫onLaunch用戶從目標(biāo)小程序切到后臺(tái)再切回來參數(shù)就丟了。這個(gè)坑我在測試階段踩過用戶反饋第二次進(jìn)來數(shù)據(jù)就沒了排查了半天才發(fā)現(xiàn)是生命周期沒覆蓋全。3. 跳轉(zhuǎn)失敗的那些錯(cuò)誤碼與排查鏈路wx.navigateToMiniProgram的 fail 回調(diào)會(huì)返回錯(cuò)誤信息但官方文檔對錯(cuò)誤碼的說明比較簡略。我把實(shí)際項(xiàng)目中遇到過的失敗情況整理了一下基本覆蓋了 90% 的場景。3.1 常見失敗原因?qū)φ毡礤e(cuò)誤信息關(guān)鍵詞根本原因解決方式appId not in navigateToMiniProgramAppIdListapp.json 未聲明目標(biāo) AppID補(bǔ)充配置并重新發(fā)版not related/no permission兩小程序未建立關(guān)聯(lián)關(guān)系目標(biāo)小程序后臺(tái)添加關(guān)聯(lián)path not foundpath 寫錯(cuò)或目標(biāo)頁面不存在核對目標(biāo)小程序頁面路徑appId invalidAppID 格式錯(cuò)誤或不存在核對 AppID 字符串fail cancel用戶在確認(rèn)彈窗點(diǎn)了取消屬正常行為做引導(dǎo)即可fail system error系統(tǒng)級異常偶發(fā)重試或降級處理3.2 一次完整的排查過程還原說個(gè)真實(shí)的排查案例。有個(gè)項(xiàng)目上線后部分安卓用戶反饋點(diǎn)擊跳轉(zhuǎn)沒反應(yīng)iOS 正常。我按下面的鏈路一步步查的第一步先看 fail 回調(diào)有沒有觸發(fā)。加了日志上報(bào)之后發(fā)現(xiàn)這些用戶的 fail 回調(diào)根本沒執(zhí)行success 也沒執(zhí)行就是卡住了。這說明問題不在 API 層面而在更前面。第二步懷疑是確認(rèn)彈窗的問題。安卓上首次跳轉(zhuǎn)的確認(rèn)彈窗如果用戶沒點(diǎn)頁面會(huì)一直等。但用戶說沒看到彈窗。這就奇怪了。第三步查基礎(chǔ)庫版本。發(fā)現(xiàn)出問題的用戶基礎(chǔ)庫版本都低于 2.0.7而這個(gè)版本正是navigateToMiniProgramAppIdList配置生效的最低版本。低于這個(gè)版本跳轉(zhuǎn)行為是不確定的可能靜默失敗。第四步驗(yàn)證。讓用戶升級微信到最新版問題消失。同時(shí)在代碼里加了基礎(chǔ)庫版本判斷低于 2.0.7 的直接走 H5 兜底方案。const version wx.getSystemInfoSync().SDKVersion if (compareVersion(version, 2.0.7) 0) { // 走 H5 兜底 wx.navigateTo({ url: /pages/fallback/index }) } else { wx.navigateToMiniProgram({ /* ... */ }) }這個(gè)案例給我的教訓(xùn)是小程序跳轉(zhuǎn)的兼容性問題很大一部分出在基礎(chǔ)庫版本上。上線前一定要用wx.getSystemInfoSync().SDKVersion做版本判斷給低版本用戶留好退路。3.3 降級方案的設(shè)計(jì)思路跳轉(zhuǎn)失敗不可怕可怕的是失敗了用戶不知道怎么辦。我的做法是設(shè)計(jì)一套降級鏈路第一優(yōu)先級wx.navigateToMiniProgram直接跳轉(zhuǎn)第二優(yōu)先級跳轉(zhuǎn)到當(dāng)前小程序內(nèi)的 H5 中轉(zhuǎn)頁頁面上放目標(biāo)小程序的二維碼或引導(dǎo)文案第三優(yōu)先級展示一個(gè)友好的錯(cuò)誤提示告訴用戶暫時(shí)無法跳轉(zhuǎn)請稍后重試這套降級方案的關(guān)鍵是第二級。H5 中轉(zhuǎn)頁雖然體驗(yàn)差一點(diǎn)但至少保證用戶有路可走不會(huì)直接流失。4. 從目標(biāo)小程序返回原小程序的完整實(shí)現(xiàn)跳過去只是第一步跳回來才是完整的閉環(huán)。微信提供了wx.navigateBackMiniProgram來實(shí)現(xiàn)返回但這里面的門道也不少。4.1 navigateBackMiniProgram 的使用條件這個(gè) API 有個(gè)硬性前提只有當(dāng)目標(biāo)小程序是通過wx.navigateToMiniProgram打開的時(shí)候才能調(diào)用wx.navigateBackMiniProgram返回。如果用戶是直接搜索進(jìn)入目標(biāo)小程序的調(diào)這個(gè) API 會(huì)失敗。所以目標(biāo)小程序那邊要做判斷const { referrerInfo } options if (referrerInfo referrerInfo.appId) { // 說明是從其他小程序跳過來的可以返回 wx.navigateBackMiniProgram({ extraData: { result: success, orderId: 12345 }, success() { console.log(返回成功) } }) }extraData同樣可以傳數(shù)據(jù)回去原小程序在App.onShow里通過options.referrerInfo.extraData接收。這個(gè)機(jī)制很適合做目標(biāo)小程序完成操作后回傳結(jié)果的場景比如下單成功后把訂單號傳回來。4.2 返回時(shí)的數(shù)據(jù)回傳與狀態(tài)同步數(shù)據(jù)回傳有個(gè)時(shí)序問題要注意。原小程序的onShow觸發(fā)時(shí)referrerInfo.extraData里的數(shù)據(jù)是目標(biāo)小程序傳回來的但此時(shí)頁面可能還沒準(zhǔn)備好渲染。我的做法是在App.onShow里先把數(shù)據(jù)存到全局然后通過事件總線或全局狀態(tài)通知頁面更新。// App.js onShow(options) { const { referrerInfo } options if (referrerInfo referrerInfo.extraData) { this.globalData.backData referrerInfo.extraData // 通知頁面 if (this.backDataCallback) { this.backDataCallback(referrerInfo.extraData) } } }頁面在onLoad時(shí)注冊回調(diào)onUnload時(shí)注銷避免內(nèi)存泄漏。這套機(jī)制跑通之后整個(gè)跳轉(zhuǎn)閉環(huán)就完整了。4.3 用戶手動(dòng)返回的處理除了代碼調(diào)用返回用戶也可能通過左上角的返回按鈕或者手勢返回。這種情況下原小程序的onShow依然會(huì)觸發(fā)但referrerInfo.extraData是空的。所以原小程序不能強(qiáng)依賴回傳數(shù)據(jù)要做好沒有回傳數(shù)據(jù)的兜底邏輯比如重新拉取一次訂單狀態(tài)。5. 審核、合規(guī)與那些容易翻車的地方功能跑通了不代表能上線。小程序跳轉(zhuǎn)涉及跨應(yīng)用導(dǎo)流微信在審核上卡得比較嚴(yán)有幾個(gè)點(diǎn)必須提前注意。5.1 跳轉(zhuǎn)功能的審核要點(diǎn)提交審核時(shí)審核員會(huì)實(shí)際測試跳轉(zhuǎn)功能。如果跳轉(zhuǎn)的目標(biāo)小程序和你的業(yè)務(wù)無關(guān)或者跳轉(zhuǎn)后內(nèi)容與描述不符很容易被駁回。我的經(jīng)驗(yàn)是在審核備注里寫清楚跳轉(zhuǎn)的業(yè)務(wù)場景和必要性確保目標(biāo)小程序已經(jīng)上線且狀態(tài)正常跳轉(zhuǎn)后的頁面內(nèi)容要和當(dāng)前小程序的業(yè)務(wù)形成合理關(guān)聯(lián)有個(gè)真實(shí)的駁回案例一個(gè)工具類小程序跳轉(zhuǎn)到電商小程序?qū)徍藛T認(rèn)為跳轉(zhuǎn)目的不明確存在導(dǎo)流嫌疑直接駁回。后來在備注里補(bǔ)充說明跳轉(zhuǎn)是為了讓用戶購買工具配套的耗材才通過。5.2 用戶體驗(yàn)層面的注意事項(xiàng)從用戶視角看小程序跳轉(zhuǎn)是一個(gè)跳出當(dāng)前應(yīng)用的行為心理上會(huì)有中斷感。幾個(gè)提升體驗(yàn)的細(xì)節(jié)跳轉(zhuǎn)前給明確的 loading 或文案提示別讓用戶覺得點(diǎn)了沒反應(yīng)跳轉(zhuǎn)失敗時(shí)給可操作的引導(dǎo)而不是一句跳轉(zhuǎn)失敗從目標(biāo)小程序返回后原小程序的狀態(tài)要能正確恢復(fù)別讓用戶重新操作一遍5.3 關(guān)于 AppID 和支付配置的安全提醒熱詞里出現(xiàn)了不少 AppID、mchid、apiv3key 這類敏感信息。這里必須強(qiáng)調(diào)小程序的 AppID 可以公開但支付相關(guān)的 mchid、apiv3key、證書路徑這些絕對不能寫在前端代碼里。我見過有開發(fā)者把支付密鑰直接寫在小程序 JS 里這是極其危險(xiǎn)的一旦被反編譯資金安全直接暴露。正確的做法是所有支付相關(guān)的簽名、密鑰操作都放在后端小程序端只負(fù)責(zé)調(diào)起支付。前端拿到的只有后端返回的支付參數(shù)用完即棄。注意任何情況下都不要把商戶密鑰、API 密鑰、證書私鑰提交到代碼倉庫更不要打包進(jìn)小程序。這類信息一旦泄露后果不是改個(gè)密碼能解決的。6. 幾個(gè)進(jìn)階場景的處理思路基礎(chǔ)功能跑通之后實(shí)際項(xiàng)目里還會(huì)遇到一些更復(fù)雜的場景這里分享幾個(gè)我處理過的。6.1 跳轉(zhuǎn)到分包頁面的路徑寫法如果目標(biāo)小程序的頁面在分包里path 要寫完整的分包路徑。比如熱詞里出現(xiàn)的subpackages/activity/pages/detail/index這就是典型的分包路徑寫法。注意分包路徑同樣不能以斜杠開頭而且分包名要和目標(biāo)小程序app.json里的subPackages配置一致。我遇到過一次跳轉(zhuǎn)失敗排查半天發(fā)現(xiàn)是目標(biāo)小程序改了分包名從subpackages改成了subPackages大小寫變了但沒通知我們。所以跨團(tuán)隊(duì)協(xié)作時(shí)目標(biāo)小程序的路徑變更一定要有同步機(jī)制。6.2 多個(gè)目標(biāo)小程序的動(dòng)態(tài)管理前面說過navigateToMiniProgramAppIdList最多 10 個(gè)而且是靜態(tài)配置。如果你的業(yè)務(wù)需要跳轉(zhuǎn)的目標(biāo)超過 10 個(gè)怎么辦我的方案是做一個(gè)跳轉(zhuǎn)中心小程序把所有的目標(biāo)小程序都關(guān)聯(lián)到它然后主小程序只跳轉(zhuǎn)到這個(gè)跳轉(zhuǎn)中心由跳轉(zhuǎn)中心再二次跳轉(zhuǎn)。這樣主小程序的 AppID 列表只需要維護(hù)一個(gè)擴(kuò)展性大大提升。代價(jià)是多了一次跳轉(zhuǎn)體驗(yàn)上會(huì)有損耗適合對跳轉(zhuǎn)頻次要求不高的場景。6.3 跳轉(zhuǎn)與登錄態(tài)的銜接如果目標(biāo)小程序需要登錄態(tài)而用戶在原小程序已經(jīng)登錄了怎么把登錄態(tài)帶過去直接傳 token 是不安全的因?yàn)?token 可能被截獲。我的做法是傳一個(gè)一次性的 code目標(biāo)小程序拿這個(gè) code 去后端換取登錄態(tài)。這樣即使 code 被截獲也是一次性的風(fēng)險(xiǎn)可控。// 原小程序 wx.navigateToMiniProgram({ appId: xxx, path: pages/index/index, extraData: { loginCode: one-time-code-xxx } }) // 目標(biāo)小程序 const code options.referrerInfo.extraData.loginCode // 用 code 去后端換 token這套機(jī)制的關(guān)鍵是 code 的有效期要短建議 5 分鐘內(nèi)且只能使用一次。7. 我在實(shí)際項(xiàng)目中總結(jié)的幾條經(jīng)驗(yàn)做了幾個(gè)涉及小程序跳轉(zhuǎn)的項(xiàng)目之后有幾條經(jīng)驗(yàn)是文檔里不會(huì)寫、但實(shí)際很管用的。第一條永遠(yuǎn)不要假設(shè)跳轉(zhuǎn)一定成功。不管是網(wǎng)絡(luò)問題、版本問題還是用戶取消跳轉(zhuǎn)失敗是常態(tài)而不是異常。代碼里必須有完整的 fail 處理和降級方案這是基本功。第二條聯(lián)調(diào)階段一定要用真機(jī)。開發(fā)者工具對跳轉(zhuǎn)的模擬和真機(jī)差異很大尤其是確認(rèn)彈窗、基礎(chǔ)庫版本這些模擬器里根本測不出來。我現(xiàn)在的習(xí)慣是功能一寫完就真機(jī)跑一遍別等到提測。第三條跨團(tuán)隊(duì)協(xié)作時(shí)把關(guān)聯(lián)配置寫進(jìn)對接文檔。AppID、關(guān)聯(lián)關(guān)系、頁面路徑、參數(shù)格式這些都要白紙黑字確認(rèn)別靠口頭溝通。我吃過虧對方說配好了結(jié)果配的是測試環(huán)境的 AppID正式環(huán)境跳不過去上線當(dāng)天才發(fā)現(xiàn)。第四條關(guān)注基礎(chǔ)庫版本的分布。微信會(huì)定期公布基礎(chǔ)庫版本占比如果你的用戶里有大量低版本用戶跳轉(zhuǎn)功能的兼容處理就要做得更厚實(shí)。我一般會(huì)把wx.getSystemInfoSync().SDKVersion的判斷邏輯封裝成一個(gè)工具函數(shù)所有涉及新 API 的地方都先過一遍版本檢查。第五條extraData 不要傳敏感信息。雖然它不像 URL 那樣直接暴露但也不是絕對安全的。token、密鑰這類東西要么走一次性 code 機(jī)制要么干脆不傳讓目標(biāo)小程序自己走登錄流程。這套跳轉(zhuǎn)方案我從最初的踩坑到后來的穩(wěn)定運(yùn)行前后迭代了三個(gè)版本?，F(xiàn)在回頭看技術(shù)本身不難難的是把各種邊界情況都考慮到把跨團(tuán)隊(duì)協(xié)作的流程理順。希望這些經(jīng)驗(yàn)?zāi)軒湍闵僮唿c(diǎn)彎路。