網絡
TIP
在小程序中使用網路相關的API時,需要注意下列問題,請開發者提前瞭解。
伺服器網域配置
每個小程序需要事先設定一個通訊功能變量名稱,小程序只可以跟指定的功能變量名稱與進行網路通信包括普通HTTPS請求(wx.request)、上傳文件(wx.uploadFile)、下載文件(wx.downloadFile)和Websocket通信(wx.connectSocket)、UDP通信(wx.createUDPSocket)、TCP通信(wx.createTCPSocket)。
網路接口只允許與同個局域網內的非本機IP以及配置過的服務器功能變量名稱通信。
配置流程
服務器功能變量名稱請在小程序後臺>小程序管理>開發管理>功能變量名稱設定中進行配置,配置時需要注意:
功能變量名稱支持https( wx.request wx.uploadFile wx.downloadFile )協定、 wss( wx.connectSocket )協定及tcp協定和udp協定;
功能變量名稱不能使用IP地址或localhost;
不可以配置埠,如 http://miniApp.com ,但請求的URL中可以包含埠,例如 http://miniApp.com:8080 。
對於wss功能變量名稱,無需配置埠,默認允許請求該功能變量名稱下所有埠。
不支持配置父功能變量名稱,使用子功能變量名稱。
網絡請求
超時時間
- 默認超時時間和最大超時時間都是60s。
- 超時時間可以在app.json中配置。
- 也可以在介面呼叫時指定逾時時間,如 wx.request({ timeout: 5000 }),單位為ms。介面呼叫的timeout配置優先權高於app.json中的配置。
使用限制。
- 網路請求的 referer header 不可設定。其格式固定為 https://appservice.wx.com/{appid}/{version}/page-frame.html,其中 {appid} 為小程序的 appid,{version} 為小程序的版本號,版本號為0表示為開發版、體驗版以及審核版本,版本號為 devtools 表示為開發者工具,其餘版本。
- wx.request wx.uploadFile wx.downloadFile 的最大併發限制是10個。
- wx.connectSocket 的最大併發限制是5個;
- 小程序進入後臺運行後,如果5s內網絡請求沒有結束,會回檔錯誤資訊fail interrupted; 在回到前臺之前,網絡請求接口調用都會無法調用。
返回值編碼
- 建議服務器返回值使用UTF-8編碼,對於非UTF-8編碼,小程序會嘗試進行轉換,但是會有轉換失敗的可能。
- 小程序會自動對BOM頭進行過濾(只過濾一個BOM頭)。
回呼函數
只要成功接收到服務器返回,無論statusCode是多少,都會進入success回檔請開發者根據業務邏輯對返回值進行判斷。
常見問題
HTTPS證書
小程序必須使用HTTPS/WSS發起網絡請求請求時系統會對服務器功能變量名稱使用的HTTPS證書進行校驗,如果校驗失敗,則請求不能成功發起由於系統限制,不同平臺對於證書要求的嚴格程度不同為了保證小程序的相容性,建議開發者按照最高標準進行證書配置,並使用相關工具檢查現有證書是否符合要求。
對證書要求如下:
- HTTPS證書必須有效;
- 證書必須被系統信任,即根證書被已系統內寘
- 部署SSL證書的網站功能變量名稱必須與證書頒發的功能變量名稱一致。
- 證書必須在有效期內。
- 證書的信任鏈必需完整(需要伺服器配置)。
- iOS不支持自簽名證書
- iOS下證書必須滿足蘋果 App Transport Security (ATS) 的要求。
- TLS必須支持1.2及以上版本部分舊Android機型還未支持TLS 1.2,請確保HTTPS服務器的TLS版本支持1.2及以下版本。
- 部分CA可能不被作業系統信任,請開發者在選擇證書時注意小程序和各系統的相關通告。
TIP
- 證書有效性可以使用openssl s_client -connect example.com:443命令驗證,也可以使用其他 線上工具
- 除了網絡請求API外,小程序中其他HTTPS請求如果出現異常,也請按上述流程進行檢查如https的圖片無法加載、音視頻無法播放等。
跳過域名校驗
在開發者工具中,可以臨時開啟開發環境不校驗請求功能變量名稱、TLS版本及HTTPS證書選項,跳過服務器功能變量名稱的校驗此時,在開發者工具中及手機開啟調試模式時,不會進行服務器功能變量名稱的校驗。
在服務器功能變量名稱配置成功後,建議開發者關閉此選項進行開發,並在各平臺下進行測試,以確認服務器功能變量名稱配置正確
TIP
- 如果手機上出現'打開調試模式可以發出請求,關閉調試模式無法發出請求'的現象,請確認是否跳過了功能變量名稱校驗,並確認服務器功能變量名稱和證書配置是否正確
- 如遇到'服務器內部錯誤',請嘗試以下辦法自查①更換瀏覽器②重繪網頁③排查文件是否放在正確的服務器根目錄下排查辦法:按照以下規則拼接網址,並且自行嘗試訪問是否成功: https://m.da9c.cn/ 檔名