小程序中网络相关的API

网络API列表：

在小程序中使用网络相关的 API 时，需要注意下列问题，请开发者提前了解

服务器域名配置

每个微信小程序需要事先设置一个通讯域名，小程序可以跟指定的域名进行网络通信。包括普通 HTTPS 请求（request）、上传文件（uploadFile）、下载文件（downloadFile) 和 WebSocket 通信（connectSocket）

配置流程

服务器域名请在"小程序后台-设置-开发设置-服务器域名" 中进行配置，配置时需要注意：

1.域名只支持 https (request、uploadFile、downloadFile) 和 wss (connectSocket) 协议；

2.域名不能使用 IP 地址或 localhost

3.域名必须经过 ICP 备案；

4.出于安全考虑，api.weixin.qq.com 不能被配置为服务器域名，相关API也不能在小程序内调用。开发者应将 appsecret 保存到后台服务器中，通过服务器使用 appsecret 获取 accesstoken，并调用相关 API。

5.对于每个接口，分别可以配置最多 20 个域名

HTTPS 证书

小程序必须使用HTTPS请求。小程序内会对服务器域名使用的HTTPS证书进行校验，如果校验失败，则请求不能成功发起。由于系统限制，不同平台对于证书要求的严格程度不同。为了保证小程序的兼容性，建议开发者按照最高标准进行证书配置，并使用相关工具检查现有证书是否符合要求

对证书要求如下：

1.HTTPS 证书必须有效。证书必须被系统信任，部署SSL证书的网站域名必须与证书颁发的域名一致，证书必须在有效期内;

2.iOS 不支持自签名证书;

3.iOS 下证书必须满足苹果 App Transport Security (ATS) 的要求;

4.TLS 必须支持 1.2 及以上版本。部分旧 Android 机型还未支持 TLS 1.2，请确保 HTTPS 服务器的 TLS 版本支持1.2及以下版本;

5.部分 CA 可能不被操作系统信任，请开发者在选择证书时注意小程序和各系统的相关通告。

6.Chrome 56/57 内核对 WoSign、StartCom 证书限制周知:Android X5内核计划将于8月份开始升级到Chrome 57内核（目前 Chrome 53），升级到 Chrome 57 内核后，会对 WoSign CA Free SSL/StartCom 证书进行部分限制。对于小程序来说，如果储存图片资源的服务器使用了上述证书，将会影响图片的正常加载。预计 Chrome 以后版本会再加大对 WoSign CA Free SSL/StartCom 证书限制，我们建议开发者提前更换其它可信证书。

Chrome 56/57 版本对 WoSign CA Free SSL/StartCom 证书限制措施如下：

1).Chrome 56 开始停止信任 2016 年 10 月 21 日后签发的 WoSign CA Free SSL/StartCom 证书；

2).Chrome 57 进一步扩大限制范围，Alexa 排名一百万外的网站都不能使用 WoSign CA Free SSL/StartCom 证书，无论证书何时签发。

附：如何检测网站是否使用了 WoSign/StartCom

1).使用最新版本的 Chrome 打开图片链接，右键 -> 检查，切换到「Security」页卡，点击「View certificate」；

2).检查证书的签发机构是否在限制范围内。

跳过域名校验

在微信开发者工具中，可以临时开启 开发环境不校验请求域名、TLS版本及HTTPS证书 选项，跳过服务器域名的校验。此时，在微信开发者工具中及手机开启调试模式时，不会进行服务器域名的校验

在服务器域名配置成功后，建议开发者关闭此选项进行开发，并在各平台下进行测试，以确认服务器域名配置正确。

如果手机上出现 “打开调试模式可以发出请求，关闭调试模式无法发出请求” 的现象，请确认是否跳过了域名校验，并确认服务器域名和证书配置是否正确

关于请求

1.默认超时时间和最大超时时间都是 60s

2.request、uploadFile、downloadFile 的最大并发限制是 10 个

3.网络请求的 referer header 不可设置。其格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html，其中 {appid} 为小程序的 appid，{version} 为小程序的版本号，版本号为 0 表示为开发版、体验版以及审核版本，版本号为 devtools 表示为开发者工具，其余为正式版本。

4.小程序进入后台运行后（非置顶聊天），如果 5s 内网络请求没有结束，会回调错误信息 fail interrupted；在回到前台之前，网络请求接口调用都会无法调用

关于服务器返回

返回值编码

1.建议服务器返回值使用 UTF-8 编码。对于非 UTF-8 编码，小程序会尝试进行转换，但是会有转换失败的可能。

2.小程序会自动对 BOM 头进行过滤。

回调

只要成功接收到服务器返回，无论statusCode是多少，都会进入success回调。请开发者根据业务逻辑对返回值进行判断

wx.request(OBJECT)

发起网络请求

OBJECT参数说明：

success返回参数说明：

data 数据说明：

最终发送给服务器的数据是 String 类型，如果传入的 data 不是 String 类型，会被转换成 String 。转换规则如下：

1.对于 GET 方法的数据，会将数据转换成 query string（encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...）

2.对于 POST 方法且 header['content-type'] 为 application/json 的数据，会对数据进行 JSON 序列化

3.对于 POST 方法且 header['content-type'] 为 application/x-www-form-urlencoded 的数据，会将数据转换成 query string （encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...）

wx.request({
  url: 'test.php', //仅为示例，并非真实的接口地址
  data: {
     x: '' ,
     y: ''
  },
  header: {
    'content-type': 'application/json' // 默认值
  },
  success: function(res) {
    console.log(res.data)
  }
})

返回值：

返回一个 requestTask 对象，通过 requestTask，可中断请求任务; 基础库 1.4.0 开始支持，低版本需做兼容处理

requestTask 对象的方法列表：

const requestTask = wx.request({
  url: 'test.php', //仅为示例，并非真实的接口地址
  data: {
     x: '' ,
     y: ''
  },
  header: {
    'content-type': 'application/json'
  },
  success: function(res) {
    console.log(res.data)
  }
})
requestTask.abort() // 取消请求任务

Bug & Tip

1.tip: content-type 默认为 'application/json';

2.bug: 开发者工具 0.10.102800 版本，header 的 content-type 设置异常；

上传 下载

wx.uploadFile(OBJECT)

将本地资源上传到开发者服务器，客户端发起一个 HTTPS POST 请求，其中 content-type 为 multipart/form-data 。使用前请先阅读说明。

如页面通过 wx.chooseImage 等接口获取到一个本地资源的临时文件路径后，可通过此接口将本地资源上传到指定服务器

OBJECT参数说明：

success返回参数说明：

wx.chooseImage({
  success: function(res) {
    var tempFilePaths = res.tempFilePaths
    wx.uploadFile({
      url: 'https://example.weixin.qq.com/upload', //仅为示例，非真实的接口地址
      filePath: tempFilePaths[0],
      name: 'file',
      formData:{
        'user': 'test'
      },
      success: function(res){
        var data = res.data
        //do something
      }
    })
  }
})

返回值：

返回一个 uploadTask 对象，通过 uploadTask，可监听上传进度变化事件，以及取消上传任务; 基础库 1.4.0 开始支持，低版本需做兼容处理

uploadTask

uploadTask 对象的方法列表：

onProgressUpdate 返回参数说明：

const uploadTask = wx.uploadFile({
    url: 'http://example.weixin.qq.com/upload', //仅为示例，非真实的接口地址
    filePath: tempFilePaths[0],
    name: 'file',
    formData:{
        'user': 'test'
    },
    success: function(res){
        var data = res.data
        //do something
    }
})
uploadTask.onProgressUpdate((res) => {
    console.log('上传进度', res.progress)
    console.log('已经上传的数据长度', res.totalBytesSent)
    console.log('预期需要上传的数据总长度', res.totalBytesExpectedToSend)
})
uploadTask.abort() // 取消上传任务

wx.downloadFile(OBJECT)

下载文件资源到本地，客户端直接发起一个 HTTP GET 请求，返回文件的本地临时路径

OBJECT参数说明：

注：文件的临时路径，在小程序本次启动期间可以正常使用，如需持久保存，需在主动调用 wx.saveFile，才能在小程序下次启动时访问得到。 注：请在 header 中指定合理的 Content-Type 字段，以保证客户端正确处理文件类型

success返回参数说明：

wx.downloadFile({
  url: 'https://example.com/audio/123', //仅为示例，并非真实的资源
  success: function(res) {
    // 只要服务器有响应数据，就会把响应内容写入文件并进入 success 回调，业务需要自行判断是否下载到了想要的内容
    if (res.statusCode === 200) {
        wx.playVoice({
          filePath: res.tempFilePath
        })
    }
  }
})

返回值：返回一个 downloadTask 对象，通过 downloadTask，可监听下载进度变化事件，以及取消下载任务

基础库 1.4.0 开始支持，低版本需做兼容处理

downloadTask

downloadTask 对象的方法列表：

onProgressUpdate 返回参数说明：

const downloadTask = wx.downloadFile({
    url: 'http://example.com/audio/123', //仅为示例，并非真实的资源
    success: function(res) {
        wx.playVoice({
            filePath: res.tempFilePath
        })
    }
})
downloadTask.onProgressUpdate((res) => {
    console.log('下载进度', res.progress)
    console.log('已经下载的数据长度', res.totalBytesWritten)
    console.log('预期需要下载的数据总长度', res.totalBytesExpectedToWrite)
})
downloadTask.abort() // 取消下载任务

tip: 6.5.3 以及之前版本的 iOS 微信客户端 header 设置无效

WebSocket

wx.connectSocket(OBJECT)

创建一个 WebSocket 连接。基础库 1.7.0 之前，一个微信小程序同时只能有一个 WebSocket 连接，如果当前已存在一个 WebSocket 连接，会自动关闭该连接，并重新创建一个 WebSocket 连接。基础库版本 1.7.0 及以后，支持存在多个 WebSokcet 连接，每次成功调用 wx.connectSocket 会返回一个新的 SocketTask

OBJECT参数说明：

wx.connectSocket({
  url: 'wss://example.qq.com',
  data:{
    x: '',
    y: ''
  },
  header:{ 
    'content-type': 'application/json'
  },
  protocols: ['protocol1'],
  method:"GET"
})

wx.onSocketOpen(CALLBACK)

监听WebSocket连接打开事件

callback 回调函数

res

wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res) {
  console.log('WebSocket连接已打开！')
})

wx.onSocketError(CALLBACK)

监听WebSocket错误

wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res){
  console.log('WebSocket连接已打开！')
})
wx.onSocketError(function(res){
  console.log('WebSocket连接打开失败，请检查！')
})

wx.sendSocketMessage(OBJECT)

通过 WebSocket 连接发送数据，需要先 wx.connectSocket，并在 wx.onSocketOpen 回调之后才能发送

OBJECT参数说明：

var socketOpen = false
var socketMsgQueue = []
wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res) {
  socketOpen = true
  for (var i = 0; i < socketMsgQueue.length; i++){
     sendSocketMessage(socketMsgQueue[i])
  }
  socketMsgQueue = []
})
function sendSocketMessage(msg) {
  if (socketOpen) {
    wx.sendSocketMessage({
      data:msg
    })
  } else {
     socketMsgQueue.push(msg)
  }
}

wx.onSocketMessage(CALLBACK)

监听WebSocket接受到服务器的消息事件

callback 回调参数

wx.connectSocket({
  url: 'test.php'
})
wx.onSocketMessage(function(res) {
  console.log('收到服务器内容：' + res.data)
})

wx.closeSocket(OBJECT)

关闭 WebSocket 连接

OBJECT参数说明：

wx.onSocketClose(CALLBACK)

监听WebSocket关闭

wx.connectSocket({
  url: 'test.php'
})
//注意这里有时序问题，如果 wx.connectSocket 还没回调 wx.onSocketOpen，而先调用 wx.closeSocket，那么就做不到关闭 WebSocket 的目的。必须在 WebSocket 打开期间调用 wx.closeSocket 才能关闭。
wx.onSocketOpen(function() {
  wx.closeSocket()
})
wx.onSocketClose(function(res) {
  console.log('WebSocket 已关闭！')
})

返回值：

返回一个 SocketTask;基础库 1.7.0 开始支持，低版本需做兼容处理

tip: 基础库 1.7.0 开始，支持同时存在 2 条 WebSocket 连接