网络
在小程序中使用网络相关的 API 时,需要注意下列问题,请开发者提前了解。
1. 服务器域名配置
每个微信小程序需要事先设置一个通讯域名,小程序只可以跟指定的域名与进行网络通信。包括普通 HTTPS 请求(wx.request
)、上传文件(wx.uploadFile
)、下载文件(wx.downloadFile
) 和 WebSocket 通信(wx.connectSocket
)
配置流程
服务器域名请在 「小程序后台-设置-开发设置-服务器域名」 中进行配置,配置时需要注意:
- 域名只支持 HTTPS (
wx.request
、wx.uploadFile
、wx.downloadFile
) 和 wss (wx.connectSocket
) 协议; - 域名不能使用 IP 地址或 localhost;
- 可以配置端口,如
https://myserver.com:8080
,但是配置后只能向https://myserver.com:8080
发起请求。 - 如果不配置端口。如
https://myserver.com
,那么请求的 URL 中也不能包含端口,甚至是默认的 443 端口也不可以。 - 域名必须经过 ICP 备案;
- 出于安全考虑,
api.weixin.qq.com
不能被配置为服务器域名,相关 API 也不能在小程序内调用。开发者应将 AppSecret 保存到后台服务器中,通过服务器使用 getAccessToken 接口获取 access_token,并调用相关 API;
对于每个接口,分别可以配置最多 20 个域名。
2. 网络请求
超时时间
默认超时时间和最大超时时间都是 60s;
超时时间可以在 app.json
中通过 networktimeout
配置。
使用限制
网络请求的 referer header 不可设置。其格式固定为
https://servicewechat.com/{appid}/{version}/page-frame.html
,其中{appid}
为小程序的 appid,{version}
为小程序的版本号,版本号为0
表示为开发版、体验版以及审核版本,版本号为devtools
表示为开发者工具,其余为正式版本。提示
因为小程序必定带上特定 Header,在后端的 API 处理上就可以判断 Header,检测到只有是自己小程序时才允许调用接口,否则直接拒绝访问。
wx.request、wx.uploadFile、wx.downloadFile 的最大并发限制是 10 个;
提示
所以一定要避免同时发送过多的网络请求
- 小程序进入后台运行后(非置顶聊天),如果 5s 内网络请求没有结束,会回调错误信息
fail interrupted
;在回到前台之前,网络请求接口调用都会无法调用。
提示
所以重要请求的 fail
流程一定要妥善处理,可以考莉再次进行一次或两次重试或明确提示用户请求失败让其手动重试
返回值编码
建议服务器返回值使用 UTF-8 编码。对于非 UTF-8 编码,小程序会尝试进行转换,但是会有转换失败的可能。
小程序会自动对 BOM 头进行过滤(只过滤一个 BOM 头)。
回调函数
只要成功接收到服务器返回,无论 statusCode
是多少,都会进入 success
回调。请开发者根据业务逻辑对返回值进行判断。
提示
所以在请求成功的时候,也要判断请求码是不是 200,并对其他状态码做合理的处理。
3. 常见问题
HTTPS 证书
小程序必须使用 HTTPS/WSS 发起网络请求。请求时系统会对服务器域名使用的 HTTPS 证书进行校验,如果校验失败,则请求不能成功发起。由于系统限制,不同平台对于证书要求的严格程度不同。为了保证小程序的兼容性,建议开发者按照最高标准进行证书配置,并使用相关工具检查现有证书是否符合要求。
跳过域名校验
在微信开发者工具中,可以临时开启 开发环境不校验请求域名、TLS 版本及 HTTPS 证书 选项,跳过服务器域名的校验。此时,在微信开发者工具中及手机开启调试模式时,不会进行服务器域名的校验。
在服务器域名配置成功后,建议开发者关闭此选项进行开发,并在各平台下进行测试,以确认服务器域名配置正确。
如果手机上出现 “打开调试模式可以发出请求,关闭调试模式无法发出请求” 的现象,请确认是否跳过了域名校验,并确认服务器域名和证书配置是否正确。