微信小程序 網(wǎng)絡(luò)

網(wǎng)絡(luò)

在小程序/小游戲中使用網(wǎng)絡(luò)相關(guān)的 API 時，需要注意下列問題，請開發(fā)者提前了解。

1. 服務(wù)器域名配置

每個微信小程序需要事先設(shè)置通訊域名，小程序只可以跟指定的域名進行網(wǎng)絡(luò)通信。包括普通 HTTPS 請求（wx.request）、上傳文件（wx.uploadFile）、下載文件（ wx.downloadFile) 和 WebSocket 通信（wx.connectSocket）。

從基礎(chǔ)庫 2.4.0 開始，網(wǎng)絡(luò)接口允許與局域網(wǎng) IP 通信，但要注意 不允許與本機 IP 通信。

從 2.7.0 開始，提供了 UDP 通信（wx.createUDPSocket)。

配置流程

服務(wù)器域名請在 「小程序后臺-開發(fā)-開發(fā)設(shè)置-服務(wù)器域名」 中進行配置，配置時需要注意：

• 域名只支持 https (wx.request、wx.uploadFile、wx.downloadFile) 和 wss (wx.connectSocket) 協(xié)議；
• 域名不能使用 IP 地址（小程序的局域網(wǎng) IP 除外）或 localhost；
• 可以配置端口，如 https://myserver.com:8080，但是配置后只能向 https://myserver.com:8080 發(fā)起請求。如果向 https://myserver.com、https://myserver.com:9091 等 URL 請求則會失敗。
• 如果不配置端口。如 https://myserver.com，那么請求的 URL 中也不能包含端口，甚至是默認的 443 端口也不可以。如果向 https://myserver.com:443 請求則會失敗。
• 域名必須經(jīng)過 ICP 備案；
• 出于安全考慮，api.weixin.qq.com 不能被配置為服務(wù)器域名，相關(guān)API也不能在小程序內(nèi)調(diào)用。 開發(fā)者應(yīng)將 AppSecret 保存到后臺服務(wù)器中，通過服務(wù)器使用 getAccessToken 接口獲取 access_token，并調(diào)用相關(guān) API；
• 對于每個接口，分別可以配置最多 20 個域名。

2. 網(wǎng)絡(luò)請求

超時時間

• 默認超時時間和最大超時時間都是 60s；
• 超時時間可以在 app.json 或 game.json 中通過 networktimeout 配置。

使用限制

• 網(wǎng)絡(luò)請求的 referer header 不可設(shè)置。其格式固定為 https://servicewechat.com/{appid}/{version}/page-frame.html，其中 {appid} 為小程序的 appid，{version} 為小程序的版本號，版本號為 0 表示為開發(fā)版、體驗版以及審核版本，版本號為 devtools 表示為開發(fā)者工具，其余為正式版本；
• wx.request、wx.uploadFile、wx.downloadFile 的最大并發(fā)限制是 10 個；
• wx.connectSocket 的最大并發(fā)限制是 5 個。
• 小程序進入后臺運行后，如果 5s 內(nèi)網(wǎng)絡(luò)請求沒有結(jié)束，會回調(diào)錯誤信息 fail interrupted；在回到前臺之前，網(wǎng)絡(luò)請求接口調(diào)用都會無法調(diào)用。

返回值編碼

• 建議服務(wù)器返回值使用 UTF-8 編碼。對于非 UTF-8 編碼，小程序會嘗試進行轉(zhuǎn)換，但是會有轉(zhuǎn)換失敗的可能。
• 小程序會自動對 BOM 頭進行過濾（只過濾一個BOM頭）。

回調(diào)函數(shù)

• 只要成功接收到服務(wù)器返回，無論 statusCode 是多少，都會進入 success 回調(diào)。請開發(fā)者根據(jù)業(yè)務(wù)邏輯對返回值進行判斷。

3. 常見問題

HTTPS 證書

小程序必須使用 HTTPS/WSS 發(fā)起網(wǎng)絡(luò)請求。請求時系統(tǒng)會對服務(wù)器域名使用的 HTTPS 證書進行校驗，如果校驗失敗，則請求不能成功發(fā)起。由于系統(tǒng)限制，不同平臺對于證書要求的嚴格程度不同。為了保證小程序的兼容性，建議開發(fā)者按照最高標準進行證書配置，并使用相關(guān)工具檢查現(xiàn)有證書是否符合要求。

對證書要求如下：

• HTTPS 證書必須有效；證書必須被系統(tǒng)信任，即根證書被已系統(tǒng)內(nèi)置部署 SSL 證書的網(wǎng)站域名必須與證書頒發(fā)的域名一致證書必須在有效期內(nèi)證書的信任鏈必需完整（需要服務(wù)器配置）
• iOS 不支持自簽名證書;
• iOS 下證書必須滿足蘋果 App Transport Security (ATS) 的要求;
• TLS 必須支持 1.2 及以上版本。部分舊 Android 機型還未支持 TLS 1.2，請確保 HTTPS 服務(wù)器的 TLS 版本支持 1.2 及以下版本;
• 部分 CA 可能不被操作系統(tǒng)信任，請開發(fā)者在選擇證書時注意小程序和各系統(tǒng)的相關(guān)通告。
  • Chrome 56/57 內(nèi)核對 WoSign、StartCom 證書限制周知

證書有效性可以使用 openssl s_client -connect example.com:443 命令驗證，也可以使用其他在線工具。

除了網(wǎng)絡(luò)請求 API 外，小程序中其他 HTTPS 請求如果出現(xiàn)異常，也請按上述流程進行檢查。如 https 的圖片無法加載、音視頻無法播放等。

跳過域名校驗

在微信開發(fā)者工具中，可以臨時開啟 開發(fā)環(huán)境不校驗請求域名、TLS版本及HTTPS證書 選項，跳過服務(wù)器域名的校驗。此時，在微信開發(fā)者工具中及手機開啟調(diào)試模式時，不會進行服務(wù)器域名的校驗。

在服務(wù)器域名配置成功后，建議開發(fā)者關(guān)閉此選項進行開發(fā)，并在各平臺下進行測試，以確認服務(wù)器域名配置正確。

如果手機上出現(xiàn) “打開調(diào)試模式可以發(fā)出請求，關(guān)閉調(diào)試模式無法發(fā)出請求” 的現(xiàn)象，請確認是否跳過了域名校驗，并確認服務(wù)器域名和證書配置是否正確。

局域網(wǎng)通信

基礎(chǔ)庫 2.4.0 提供了 wx.startLocalServiceDiscovery 等一系列 mDNS API，可以用來獲取局域網(wǎng)內(nèi)提供 mDNS 服務(wù)的設(shè)備的 IP。 wx.request/wx.connectSocket/wx.uploadFile/wx.downloadFile 的 url 參數(shù)允許為 ${IP}:${PORT}/${PATH} 的格式，當且僅當 IP 與手機 IP 處在同一網(wǎng)段且不與本機 IP 相同（一般來說，就是同一局域網(wǎng)，如連接在同一個 wifi 下）時，請求/連接才會成功。

在這種情況下，不會進行安全域的校驗，不要求必須使用 https/wss，也可以使用 http/ws。

wx.request({
  url: 'http://10.9.176.40:828'
  // 省略其他參數(shù)
})

wx.connectSocket({
  url: 'ws://10.9.176.42:828'
  // 省略其他參數(shù)
})

基礎(chǔ)庫 2.7.0 開始，提供了 wx.createUDPSocket 接口用于進行 UDP 通信。通信規(guī)則同上，僅允許同一局域網(wǎng)下的非本機 IP。

mDNS

目前小程序只支持通過 mDNS 協(xié)議獲取局域網(wǎng)內(nèi)其他設(shè)備的 IP。iOS 上 mDNS API 的實現(xiàn)基于 Bonjour，Android 上則是基于 Android 系統(tǒng)接口。

serviceType

發(fā)起 mDNS 服務(wù)搜索 wx.startLocalServiceDiscovery 的接口有 serviceType 參數(shù)，指定要搜索的服務(wù)類型。

serviceType 的格式和規(guī)范，iOS Bonjour Overview 在 Bonjour Names for Existing Service Types 有提及。

Android 文檔 對此也有提及。