QQ小游戲 網(wǎng)絡(luò)

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

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

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

配置流程

服務(wù)器域名請(qǐng)?jiān)?「小程序后臺(tái)-設(shè)置-開發(fā)設(shè)置-服務(wù)器域名」 中進(jìn)行配置，配置時(shí)需要注意：

1. 域名只支持 https (qq.request、qq.uploadFile、qq.downloadFile ) 和 wss (qq.connectSocket) 協(xié)議；
2. 域名不能使用 IP 地址或 localhost；
3. 可以配置端口，如 https://myserver.com:8080，但是配置后只能向 https://myserver.com:8080 發(fā)起請(qǐng)求。如果向 https://myserver.com、https://myserver.com:9091 等 URL 請(qǐng)求則會(huì)失敗。
4. 如果不配置端口。如 https://myserver.com，那么請(qǐng)求的 URL 中也不能包含端口，甚至是默認(rèn)的 443 端口也不可以。如果向 https://myserver.com:443 請(qǐng)求則會(huì)失敗。
5. 域名必須經(jīng)過(guò) ICP 備案；
6. 對(duì)于每個(gè)接口，分別可以配置最多 20 個(gè)域名。

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

超時(shí)時(shí)間

默認(rèn)超時(shí)時(shí)間和最大超時(shí)時(shí)間都是 60s； 超時(shí)時(shí)間可以在 app.json 中配置。

返回值編碼

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

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

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

3. 常見(jiàn)問(wèn)題

HTTPS 證書

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

• HTTPS 證書必須有效；
  • 證書必須被系統(tǒng)信任，即根證書被已系統(tǒng)內(nèi)置
  • 部署 SSL 證書的網(wǎng)站域名必須與證書頒發(fā)的域名一致
  • 證書必須在有效期內(nèi)
  • 證書的信任鏈必需完整（需要服務(wù)器配置）
• iOS 不支持自簽名證書;
• iOS 下證書必須滿足蘋果 App Transport Security (ATS) 的要求;
• TLS 必須支持 1.2 及以上版本。部分舊 Android 機(jī)型還未支持 TLS 1.2，請(qǐng)確保 HTTPS 服務(wù)器的 TLS 版本支持 1.2 及以下版本;
• 部分 CA 可能不被操作系統(tǒng)信任，請(qǐng)開發(fā)者在選擇證書時(shí)注意小程序和各系統(tǒng)的相關(guān)通告。
• 證書有效性可以使用 openssl s_client -connect example.com:443 命令驗(yàn)證，也可以使用其他在線工具 。
• 除了網(wǎng)絡(luò)請(qǐng)求 API 外，小程序中其他 HTTPS 請(qǐng)求如果出現(xiàn)異常，也請(qǐng)按上述流程進(jìn)行檢查。如 https 的圖片無(wú)法加載、音視頻無(wú)法播放等。

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

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

跳過(guò)域名校驗(yàn)

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

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

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