UniApp 网络

1. 发起请求

1.1. `uni.request(OBJECT)`

发起网络请求。

提示

在各个小程序平台运行时，网络相关的 API 在使用前需要配置域名白名单。

1.1.1. `request` 兼容性

HarmonyOS
HBuilderX 4.23

1.1.2. `OBJECT` 参数说明

参数名	类型	必填	默认值	说明	平台差异说明
`url`	`String`	是		开发者服务器接口地址
`data`	`Object`/`String`/`ArrayBuffer`	否		请求的参数	App 3.3.7 以下不支持 `ArrayBuffer` 类型
`header`	`Object`	否		设置请求的 Header，`header` 中不能设置 `Referer`	App、H5 端会自动带上 cookie，且 H5 端不可手动修改
`method`	`String`	否	`GET`	有效值详见下方说明
`timeout`	`Number`	否	`60000`	超时时间，单位 `ms`	H5（HBuilderX 2.9.9+）、APP（HBuilderX 2.9.9+）、微信小程序（2.10.0）、支付宝小程序
`dataType`	`String`	否	`json`	如果设为 `json`，会对返回的数据进行一次 `JSON.parse`，非 `json` 不会进行 `JSON.parse`
`responseType`	`String`	否	`text`	设置响应的数据类型。合法值：`text`、`arraybuffer`	支付宝小程序不支持
`sslVerify`	`Boolean`	否	`true`	验证 ssl 证书	仅 App 安卓端支持（HBuilderX 2.3.3+），不支持离线打包
`withCredentials`	`Boolean`	否	`false`	跨域请求时是否携带凭证（cookies）	仅 H5 支持（HBuilderX 2.6.15+）
`firstIpv4`	`Boolean`	否	`false`	DNS 解析时优先使用 ipv4	仅 App-Android 支持（HBuilderX 2.8.0+）
`enableHttp2`	`Boolean`	否	`false`	开启 http2	微信小程序
`enableQuic`	`Boolean`	否	`false`	开启 quic	微信小程序
`enableCache`	`Boolean`	否	`false`	开启 cache	微信小程序、抖音小程序 2.31.0+
`enableHttpDNS`	`Boolean`	否	`false`	是否开启 HttpDNS 服务。如开启，需要同时填入 `httpDNSServiceId`。HttpDNS 用法详见移动解析 HttpDNS	微信小程序
`httpDNSServiceId`	`String`	否		HttpDNS 服务商 Id。HttpDNS 用法详见移动解析 HttpDNS	微信小程序
`enableChunked`	`Boolean`	否	`false`	开启 transfer-encoding chunked	微信小程序
`forceCellularNetwork`	`Boolean`	否	`false`	wifi 下使用移动网络发送请求	微信小程序
`enableCookie`	`Boolean`	否	`false`	开启后可在 headers 中编辑 cookie	支付宝小程序 10.2.33+
`cloudCache`	`Object`/`Boolean`	否	`false`	是否开启云加速（详见云加速服务）	百度小程序 3.310.11+
`defer`	`Boolean`	否	`false`	控制当前请求是否延时至首屏内容渲染后发送	百度小程序 3.310.11+
`success`	`Function`	否		收到开发者服务器成功返回的回调函数
`fail`	`Function`	否		接口调用失败的回调函数
`complete`	`Function`	否		接口调用结束的回调函数（调用成功、失败都会执行）

1.1.2.1. `method` 有效值

注意：method 有效值必须大写，每个平台支持的 method 有效值不同，详细见下表。

method	App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	快手小程序	京东小程序
`GET`	√	√	√	√	√	√	√	√
`POST`	√	√	√	√	√	√	√	√
`PUT`	√	√	√	x	√	√	x	x
`DELETE`	√	√	√	x	√	x	x	x
`CONNECT`	x	√	√	x	x	x	x	x
`HEAD`	√	√	√	x	√	x	x	x
`OPTIONS`	√	√	√	x	√	x	x	x
`TRACE`	x	√	√	x	x	x	x	x

1.1.2.2. `success` 返回参数说明

参数	类型	说明
`data`	`Object`/`String`/`ArrayBuffer`	开发者服务器返回的数据
`statusCode`	`Number`	开发者服务器返回的 HTTP 状态码
`header`	`Object`	开发者服务器返回的 HTTP Response Header
`cookies`	`Array.<String>`	开发者服务器返回的 cookies，格式为字符串数组

1.1.2.3. `data` 数据说明

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

对于 GET 方法，会将数据转换为 query string。例如 { name: 'name', age: 18 } 转换后的结果是 name=name&age=18。
对于 POST 方法且 header['content-type'] 为 application/json 的数据，会进行 JSON 序列化。
对于 POST 方法且 header['content-type'] 为 application/x-www-form-urlencoded 的数据，会将数据转换为 query string。

示例：

JavaScript

uni.request({
  url: "https://www.example.com/request", // 仅为示例，并非真实接口地址。
  data: {
    text: "uni.request",
  },
  header: {
    "custom-header": "hello", // 自定义请求头信息
  },
  success: (res) => {
    console.log(res.data);
    this.text = "request success";
  },
});

1.1.3. 返回值

如果希望返回一个 RequestTask 对象，需要至少传入 success/fail/complete 参数中的一个。例如：

JavaScript

var requestTask = uni.request({
  url: "https://www.example.com/request", // 仅为示例，并非真实接口地址。
  complete: () => {},
});
requestTask.abort();

如果没有传入 success/fail/complete 参数，则会返回封装后的 Promise 对象：Promise 封装。

1.1.3.1. `RequestTask`

通过 RequestTask，可中断请求任务。

RequestTask 对象的方法列表：

方法	参数	说明
`abort`		中断请求任务
`offHeadersReceived`		取消监听 HTTP Response Header 事件，仅微信小程序平台支持，文档详情
`onHeadersReceived`		监听 HTTP Response Header 事件。会比请求完成事件更早，仅微信小程序平台支持，文档详情

abort(): void 兼容性：

HarmonyOS
HBuilderX 4.23

示例：

JavaScript

const requestTask = uni.request({
  url: "https://www.example.com/request", // 仅为示例，并非真实接口地址。
  data: {
    name: "name",
    age: 18,
  },
  success: function (res) {
    console.log(res.data);
  },
});

// 中断请求任务
requestTask.abort();

1.1.4. 注意事项

请求的 header 中 content-type 默认为 application/json。
避免在 header 中使用中文，或者使用 encodeURIComponent 进行编码，否则在百度小程序报错。（来自：快狗打车前端团队）
网络请求的超时时间可以统一在 manifest.json 中配置 networkTimeout。
H5 端本地调试需注意跨域问题，参考：调试跨域问题解决方案。
注意由于百度小程序 iOS 客户端，请求失败时会进入 fail 回调，需要针对百度增加相应的处理以解决该问题。
注意小程序端不支持自动保持 cookie，服务器应避免验证 cookie。如果服务器无法修改，也可以使用一些模拟手段，比如这样的工具 https://github.com/charleslo1/weapp-cookie 可以请求时带上 cookie 并将响应的 cookie 保存在本地。
H5 端 cookie 受跨域限制（和平时开发网站时一样），旧版的 uni.request 未支持 withCredentials 配置，可以直接使用 xhr 对象或者其他类库。
根据 W3C 规范，H5 端无法获取 response header 中 Set-Cookie、Set-Cookie2 这 2 个字段，对于跨域请求，允许获取的 response header 字段只限于 “simple response header” 和 “Access-Control-Expose-Headers”（详情）。
uni-app 插件市场有 flyio、axios 等三方封装的拦截器可用。
低版本手机自身不支持 ipv6，如果服务器仅允许 ipv6，会导致老手机无法正常运行或访问速度非常慢。
localhost、127.0.0.1 等服务器地址，只能在电脑端运行，手机端连接时不能访问。请使用标准 IP 并保证手机能连接电脑网络。
debug 模式，安卓端暂时无法获取响应头，url 中含有非法字符（如未编码为 %20 的空格）时会请求失败。
iOS App 第一次安装启动后，会弹出是否允许联网的询问框，在用户点击同意前，调用联网 API 会失败。请注意判断这种情况。比如官方提供的新闻模板示例（HBuilderX 新建项目可选择），会判断如果无法联网，则提供一个错误页，提示用户设置网络及下拉刷新重试。
良好体验的 App，还会判断当前是否处于飞行模式（参考）、是 wifi 还是 3G（参考）。
部分安卓设备，真机运行或 debug 模式下的网速，低于 release 模式很多。
使用一些比较小众的证书机构（如：CFCA OV OCA）签发的 ssl 证书在安卓设备请求会失败，因为这些机构的根证书不在系统内置根证书库，可以更换其他常见机构签发的证书（如：Let's Encrypt），或者配置 sslVerify 为 false 关闭 ssl 证书验证（不推荐）。
离线打包不支持 sslVerify 配置。
单次网络请求数据量建议控制在 50K 以下（仅指 json 数据，不含图片），过多数据应分页获取，以提升应用体验。

1.2. `uni.configMTLS(OBJECT)`

https 请求配置自签名证书。

App	HarmonyOS Next	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ 小程序	快手小程序	京东小程序
3.2.7+	x	x	x	x	x	x	x	x	x

1.2.1. `OBJECT` 参数说明

参数	类型	必填	说明
`certificates`	`Array<certificate>`	是	`certificates` 为数组，支持为多个域名配置自签名证书
`success`	`Function(callbackObject)`	否	接口调用成功的回调函数
`fail`	`Function(callbackObject)`	否	接口调用失败的回调函数
`complete`	`Function`	否	接口调用结束的回调函数（调用成功、失败都会执行）

1.2.1.1. `certificate` 参数说明

证书配置项：

参数	类型	必填	说明
`host`	`String`	是	对应请求的域名（注意：不要协议部分）
`client`	`String`	否	客户端证书（服务器端需要验证客户端证书时需要配置此项，格式要求请参考下面的证书格式说明，注意 `iOS` 平台客户端证书只支持 `.p12` 类型的证书。HarmonyOS Next 上是证书路径，文档）
`keyPath`	`String`	否	证书秘钥的路径，只支持 HarmonyOS Next（HBuilderX 4.31）
`clientPassword`	`String`	否	客户端证书对应的密码（客户端证书存在时必须配置此项。HarmonyOS Next 上是证书秘钥的密码，文档）
`server`	`Array<String>`	否	服务器端证书（客户端需要对服务器端证书做校验时需要配置此项，通常使用自签名证书时才需要配置，格式要求请参考下面的证书格式说明，注意 `iOS` 平台服务器端证书只支持 `.cer` 类型的证书，不仅仅验证公钥，还要验证整个证书链，请保证证书的完整性。HarmonyOS Next 不支持）

证书支持两种格式，文件格式和 Base64 字符串格式：

文件格式说明：可将证书文件放到工程的 static 目录中（当然也可以通过请求下载到本地），然后填写文件路径，示例：/static/client.p12。
Base64String 格式说明：将证书文件的二进制转换为 Base64String 字符串，然后在字符串前面添加 data:cert/pem;base64, 前缀，示例：data:cert/pem;base64,xxx，xxx 代表真实的证书 base64String。

1.2.1.2. `callbackObject` 参数说明

属性	类型	说明
`code`	`Number`	成功返回 `0`，失败返回相应 code 码

示例：

JavaScript

uni.configMTLS({
  certificates: [
    {
      host: "www.test.com",
      client: "/static/client.p12",
      clientPassword: "123456789",
      server: ["/static/server.cer"],
    },
  ],
  success({ code }) {},
});

2. 上传、下载

2.1. `uni.uploadFile(OBJECT)`

将本地资源上传到开发者服务器，客户端发起一个 POST 请求，其中 content-type 为 multipart/form-data。如页面通过 uni.chooseImage 等接口获取到一个本地资源的临时文件路径后，可通过此接口将本地资源上传到指定服务器。另外选择和上传非图像、视频文件参考：https://ask.dcloud.net.cn/article/35547。

提示

在各个小程序平台运行时，网络相关的 API 在使用前需要配置域名白名单。

推荐开发者上传到 uniCloud，uniCloud 提供了免费 CDN 和更好的易用性，包括安全的 cdn 直传。

uniCloud 的上传 API：https://doc.dcloud.net.cn/uniCloud/storage/dev.html#uploadfile；
封装的更完善的 uni-file-picker 组件，文件选择、上传到 uniCloud，一站式集成；
推荐 uni-cdn，帮你节省至少 30% 的 CDN 费用！详情；

2.1.1. `uploadFile` 兼容性

HarmonyOS
HBuilderX 4.23

2.1.2. `OBJECT` 参数说明

参数名	类型	必填	说明	平台差异说明
`url`	`String`	是	开发者服务器 `url`
`files`	`Array`	是（`files` 和 `filePath` 选其一）	需要上传的文件列表。使用 `files` 时，`filePath` 和 `name` 不生效	App、H5（2.6.15+）
`fileType`	`String`	见平台差异说明	文件类型，`image`/`video`/`audio`	仅支付宝小程序，且必填
`file`	`File`	否	要上传的文件对象	仅 H5（2.6.15+）支持
`filePath`	`String`	是（`files` 和 `filePath` 选其一）	要上传文件资源的路径
`name`	`String`	是	文件对应的 `key`，开发者在服务器端通过这个 `key` 可以获取到文件二进制内容
`header`	`Object`	否	HTTP 请求的 Header，`header` 中不能设置 `Referer`
`timeout`	`Number`	否	超时时间，单位 `ms`	H5（HBuilderX 2.9.9+）、APP（HBuilderX 2.9.9+）、微信小程序、支付宝小程序、抖音小程序、快手小程序
`formData`	`Object`	否	HTTP 请求中其他额外的 form data
`success`	`Function`	否	接口调用成功的回调函数
`fail`	`Function`	否	接口调用失败的回调函数
`complete`	`Function`	否	接口调用结束的回调函数（调用成功、失败都会执行）

注意：

App 支持多文件上传，微信小程序只支持单文件上传，传多个文件需要反复调用本 API。所以跨端的写法就是循环调用本 API。
hello uni-app 中的客服反馈，支持多图上传。uni-app 插件市场中也有多个封装的组件。
App 平台选择和上传非图像、视频文件，参考 https://ask.dcloud.net.cn/article/35547。
网络请求的超时时间可以统一在 manifest.json 中配置 networkTimeout。
支付宝小程序开发工具上传文件返回的 http 状态码为字符串形式，支付宝小程序真机返回的状态码为数字形式。

2.1.2.1. `files` 参数说明

files 参数是一个 file 对象的数组，file 对象的结构如下：

参数名	类型	必填	说明
`name`	`String`	否	multipart 提交时，表单的项目名，默认为 `file`
`file`	`File`	否	要上传的文件对象，仅 H5（2.6.15+）支持
`uri`	`String`	是	文件的本地地址

如果 name 不填或填的值相同，可能导致服务端读取文件时只能读取到一个文件。

2.1.2.2. `success` 返回参数说明

参数	类型	说明
`data`	`String`	开发者服务器返回的数据
`statusCode`	`Number`	开发者服务器返回的 HTTP 状态码

示例：

JavaScript

uni.chooseImage({
  success: (chooseImageRes) => {
    const tempFilePaths = chooseImageRes.tempFilePaths;
    uni.uploadFile({
      url: "https://www.example.com/upload", // 仅为示例，非真实的接口地址
      filePath: tempFilePaths[0],
      name: "file",
      formData: {
        user: "test",
      },
      success: (uploadFileRes) => {
        console.log(uploadFileRes.data);
      },
    });
  },
});

2.1.3. 返回值

如果希望返回一个 uploadTask 对象，需要至少传入 success/fail/complete 参数中的一个。例如：

JavaScript

var uploadTask = uni.uploadFile({
  url: "https://www.example.com/upload", // 仅为示例，并非真实接口地址。
  complete: () => {},
});
uploadTask.abort();

如果没有传入 success/fail/complete 参数，则会返回封装后的 Promise 对象：Promise 封装。

通过 uploadTask，可监听上传进度变化事件，以及取消上传任务。

2.1.3.1. `uploadTask` 对象的方法列表

方法	参数	说明
`abort`		中断上传任务
`onProgressUpdate`	`callback`	监听上传进度变化
`onHeadersReceived`	`callback`	监听 HTTP Response Header 事件。会比请求完成事件更早，仅微信小程序平台支持，规范详情
`offProgressUpdate`	`callback`	取消监听上传进度变化事件，仅微信小程序平台支持，规范详情
`offHeadersReceived`	`callback`	取消监听 HTTP Response Header 事件，仅微信小程序平台支持，规范详情

abort(): void 中断上传任务，兼容性：
HarmonyOS
HBuilderX 4.23
onProgressUpdate(callback: UploadFileProgressUpdateCallback): void 监听上传进度变化，兼容性：
HarmonyOS
HBuilderX 4.23
各方法 callback 参数，其函数签名为：(result: OnProgressUpdateResult) => void。

`onProgressUpdate` 返回参数说明

参数	类型	说明
`progress`	`Number`	上传进度百分比
`totalBytesSent`	`Number`	已经上传的数据长度，单位 Bytes
`totalBytesExpectedToSend`	`Number`	预期需要上传的数据总长度，单位 Bytes

`OnProgressUpdateResult` 的属性值

名称	类型	必填	默认值	兼容性	描述
`progress`	`Number`	是	-	√	上传进度百分比
`totalBytesSent`	`Number`	是	-	√	已经上传的数据长度，单位 Bytes
`totalBytesExpectedToSend`	`Number`	是	-	√	预期需要上传的数据总长度，单位 Bytes

2.1.4. 示例

JavaScript

uni.chooseImage({
  success: (chooseImageRes) => {
    const tempFilePaths = chooseImageRes.tempFilePaths;
    const uploadTask = uni.uploadFile({
      url: "https://www.example.com/upload", // 仅为示例，非真实的接口地址
      filePath: tempFilePaths[0],
      name: "file",
      formData: {
        user: "test",
      },
      success: (uploadFileRes) => {
        console.log(uploadFileRes.data);
      },
    });

    uploadTask.onProgressUpdate((res) => {
      console.log("上传进度" + res.progress);
      console.log("已经上传的数据长度" + res.totalBytesSent);
      console.log("预期需要上传的数据总长度" + res.totalBytesExpectedToSend);

      // 测试条件，取消上传任务。
      if (res.progress > 50) {
        uploadTask.abort();
      }
    });
  },
});

2.2. `uni.downloadFile(OBJECT)`

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

提示

在各个小程序平台运行时，网络相关的 API 在使用前需要配置域名白名单。在 h5 上是跨域的，用户需要处理好跨域问题。

2.2.1. `downloadFile` 兼容性

HarmonyOS
HBuilderX 4.23

2.2.2. `OBJECT` 参数说明

参数名	类型	必填	说明	平台差异说明
`url`	`String`	是	下载资源的 url
`header`	`Object`	否	HTTP 请求的 Header，`header` 中不能设置 `Referer`
`timeout`	`Number`	否	超时时间，单位 `ms`	H5、APP、微信小程序、支付宝小程序、抖音小程序、快手小程序
`filePath`	`String`	否	指定文件下载后存储的路径（本地路径）	小程序端支持（微信 IOS 小程序保存到相册需要添加此字段才可以正常保存）
`success`	`Function`	否	下载成功后以 `tempFilePath` 的形式传给页面，`res = {tempFilePath: '文件的临时路径'}`
`fail`	`Function`	否	接口调用失败的回调函数
`complete`	`Function`	否	接口调用结束的回调函数（调用成功、失败都会执行）

提示

文件的临时路径，在应用本次启动期间可以正常使用，如需持久保存，需在主动调用 uni.saveFile，才能在应用下次启动时访问得到。

网络请求的超时时间可以统一在 manifest.json 中配置 networkTimeout。

2.2.2.1. `success` 返回参数说明

参数	类型	说明	平台差异说明
`tempFilePath`	`String`	临时文件路径，下载后的文件会存储到一个临时文件	微信小程序、支付宝小程序、百度小程序、抖音小程序、飞书小程序
`statusCode`	`Number`	开发者服务器返回的 HTTP 状态码	微信小程序、QQ 小程序、百度小程序、抖音小程序、飞书小程序
`apFilePath`	`String`	下载文件保存的路径（本地临时文件）。入参未指定 `filePath` 的情况下可用	支付宝小程序
`filePath`	`String`	用户文件路径（本地路径）。传入 `filePath` 时会返回，跟传入的 `filePath` 一致	微信小程序、支付宝小程序、抖音小程序、飞书小程序
`fileContent`	`Buffer`	文件内容	QQ 小程序

2.2.3. 返回值

如果希望返回一个 downloadTask 对象，需要至少传入 success/fail/complete 参数中的一个。例如：

JavaScript

var downloadTask = uni.downloadFile({
  url: "https://www.example.com/file/test", // 仅为示例，并非真实接口地址。
  complete: () => {},
});
downloadTask.abort();

如果没有传入 success/fail/complete 参数，则会返回封装后的 Promise 对象：Promise 封装。

通过 downloadTask，可监听下载进度变化事件，以及取消下载任务。

2.2.3.1. `downloadTask` 对象的方法列表

方法	参数	说明	最低版本
`abort`		中断下载任务	*
`onProgressUpdate`	`callback`	监听下载进度变化	*
`onHeadersReceived`	`callback`	监听 HTTP Response Header 事件，会比请求完成事件更早，仅微信小程序平台支持，规范详情
`offProgressUpdate`	`callback`	取消监听下载进度变化事件，仅微信小程序平台支持，规范详情
`offHeadersReceived`	`callback`	取消监听 HTTP Response Header 事件，仅微信小程序平台支持，规范详情

abort(): void 中断下载任务，兼容性：
HarmonyOS
HBuilderX 4.23
onProgressUpdate(callback: DownloadFileProgressUpdateCallback): void 监听下载进度变化，兼容性：
HarmonyOS
HBuilderX 4.23
各方法 callback 参数，其函数签名为：(result: OnProgressDownloadResult) => void。

`onProgressUpdate` 返回参数说明

参数	类型	说明
`progress`	`Number`	下载进度百分比
`totalBytesWritten`	`Number`	已经下载的数据长度，单位 Bytes
`totalBytesExpectedToWrite`	`Number`	预期需要下载的数据总长度，单位 Bytes

`OnProgressDownloadResult` 的属性值

名称	类型	必填	默认值	兼容性	描述
`progress`	`Number`	是	-	√	下载进度百分比
`totalBytesWritten`	`Number`	是	-	√	已经下载的数据长度，单位 Bytes
`totalBytesExpectedToWrite`	`Number`	是	-	√	预期需要下载的数据总长度，单位 Bytes

2.2.4. 示例

JavaScript

const downloadTask = uni.downloadFile({
  url: "http://www.example.com/file/test", // 仅为示例，并非真实的资源
  success: (res) => {
    if (res.statusCode === 200) {
      console.log("下载成功");
    }
  },
});

downloadTask.onProgressUpdate((res) => {
  console.log("下载进度" + res.progress);
  console.log("已经下载的数据长度" + res.totalBytesWritten);
  console.log("预期需要下载的数据总长度" + res.totalBytesExpectedToWrite);

  // 满足测试条件，取消下载任务。
  if (res.progress > 50) {
    downloadTask.abort();
  }
});

3. WebSocket

3.1. `uni.connectSocket(OBJECT)`

创建一个 WebSocket 连接。

提示

在各个小程序平台运行时，网络相关的 API 在使用前需要配置域名白名单。

uni-app 的 socket，分全局 socket 和 socketTask。全局 socket 只能有一个，一旦被占用就无法再开启。所以不推荐使用全局 socket，一般使用 socketTask。

小程序上，socketTask 也有数量限制，具体需要参阅各家小程序文档。

注意：小程序的运行日志回显、uniPush 的小程序版，均基于 socket，都会占用 socketTask 通道数量。运行日志回显是可以关闭的，详见。

3.1.1. `connectSocket` 兼容性

HarmonyOS
HBuilderX 4.23

3.1.2. `OBJECT` 参数说明

参数名	类型	必填	说明	平台差异说明
`url`	`String`	是	服务器接口地址	小程序中必须是 `wss://` 协议
`multiple`	`Boolean`	否	是否多实例。传入 `true` 时，将返回一个包含 `SocketTask` 实例	仅支付宝小程序支持
`header`	`Object`	否	HTTP 请求的 Header，`header` 中不能设置 `Referer`	小程序、App 2.9.6+
`method`	`String`	否	默认是 GET，有效值：`OPTIONS`、`GET`、`HEAD`、`POST`、`PUT`、`DELETE`、`TRACE`、`CONNECT`	仅微信小程序支持
`protocols`	`Array<String>`	否	子协议数组	App、H5、微信小程序、百度小程序、抖音小程序、飞书小程序
`success`	`Function`	否	接口调用成功的回调函数
`fail`	`Function`	否	接口调用失败的回调函数
`complete`	`Function`	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码：

JavaScript

uni.connectSocket({
  url: "wss://www.example.com/socket",
  header: {
    "content-type": "application/json",
  },
  protocols: ["protocol1"],
  method: "GET",
});

3.1.3. 返回值

如果希望返回一个 socketTask 对象，需要至少传入 success/fail/complete 参数中的一个。例如：

JavaScript

var socketTask = uni.connectSocket({
  url: "wss://www.example.com/socket", // 仅为示例，并非真实接口地址。
  complete: () => {},
});

如果没有传入 success/fail/complete 参数，则会返回封装后的 Promise 对象：Promise 封装。

3.1.3.1. `SocketTask` 对象的方法列表

send(options: SendSocketMessageOptions): void：通过 WebSocket 连接发送数据；
兼容性
HarmonyOS
HBuilderX 4.23
close(options: CloseSocketOptions): void：关闭 WebSocket 连接；
兼容性
HarmonyOS
HBuilderX 4.23
onOpen(callback: (result: OnSocketOpenCallbackResult) => void): void：监听 WebSocket 连接打开事件；
兼容性
HarmonyOS
HBuilderX 4.23
onClose(callback: (result: any) => void): void：监听 WebSocket 连接关闭事件；
兼容性
HarmonyOS
HBuilderX 4.23
onError(callback: (result: GeneralCallbackResult) => void): void：监听 WebSocket 错误；
兼容性
HarmonyOS
HBuilderX 4.23
onMessage(callback: (result: OnSocketMessageCallbackResult) => void): void：监听 WebSocket 接受到服务器的消息事件；
兼容性
HarmonyOS
HBuilderX 4.23

`SendSocketMessageOptions` 的属性值

名称	类型	必填	默认值	兼容性	描述
`data`	`any`	是	-	√	需要发送的内容，app 平台从 4.61 版本开始支持 `ArrayBuffer`
`success`	`(result: GeneralCallbackResult) => void`	否	`null`	-	接口调用成功的回调函数
`fail`	`(result: SendSocketMessageFail) => void`	否	`null`	-	接口调用失败的回调函数
`complete`	`(result: any) => void`	否	`null`	-	接口调用结束的回调函数（调用成功、失败都会执行）

`SendSocketMessageFail` 的属性值

名称	类型	必填	默认值	兼容性	描述
`errCode`	`Number`	是	-	-	错误码
`errSubject`	`String`	是	-	-	统一错误主题（模块）名称
`data`	`any`	否	-	-	错误信息中包含的数据
`cause`	`Error`	否	-	-	源错误信息，可以包含多个错误，详见 `SourceError`
`errMsg`	`String`	是	-	-	-

`CloseSocketOptions` 的属性值

名称	类型	必填	默认值	兼容性	描述
`code`	`Number`	否	`1000`	√	一个数字值表示关闭连接的状态号，表示连接被关闭的原因。如果这个参数没有被指定，默认的取值是 `1000`（表示正常连接关闭）
`reason`	`String`	否	`""`	√	一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于 123 字节的 UTF-8 文本（不是字符）
`success`	`(result: GeneralCallbackResult) => void`	否	`null`	-	接口调用成功的回调函数
`fail`	`(result: GeneralCallbackResult) => void`	否	`null`	-	接口调用失败的回调函数
`complete`	`(result: GeneralCallbackResult) => void`	否	`null`	-	接口调用结束的回调函数（调用成功、失败都会执行）

`OnSocketOpenCallbackResult` 的属性值

名称	类型	必填	默认值	兼容性	描述
`header`	`any`	是	-	√	连接成功的 HTTP 响应 Header

`OnSocketMessageCallbackResult` 的属性值

名称	类型	必填	默认值	兼容性	描述
`data`	`any`	是	-	√	服务器返回的消息，app 平台从 4.61 版本开始支持 `ArrayBuffer`

3.1.4. 注意事项

网络请求的超时时间可以统一在 manifest.json 中配置 networkTimeout。
App 平台，2.2.6 以下的版本，不支持 ArrayBuffer 类型的数据收发。老版本不愿升级也可以使用 plus-websocket 插件插件替代。
App 平台 2.2.6 以下的版本，所有 vue 页面只能使用一个 WebSocket 连接。App 下可以使用 plus-websocket 插件替代实现多连接。
微信小程序平台 1.7.0 及以上版本，最多可以同时存在 5 个 WebSocket 连接。老版本只支持一个 socket 连接。
百度小程序平台自基础库版本 1.9.4 及以后支持多个 socket 连接。老版本只支持一个 socket 连接。
QQ 小程序、支付宝小程序平台最多支持同时存在 5 个 socket 连接。
uni-push2.0 在 web、小程序以及 APP 的非离线模式下的底层实现都是基于一个 socket。如果你的项目需要再次使用 socket，请通过 SocketTask 实现。

3.2. `uni.onSocketOpen(CALLBACK)`

监听 WebSocket 连接打开事件。

警告

已废弃，使用 SocketTask 的 onOpen 替换。

平台兼容性：

抖音小程序不支持；

3.2.1. `onSocketOpen` 兼容性

HarmonyOS
HBuilderX 4.23

3.2.2. `CALLBACK` 返回参数

属性	类型	说明
`header`	`Object`	连接成功的 HTTP 响应 Header

3.2.3. 示例代码

JavaScript

uni.connectSocket({
  url: "wss://www.example.com/socket",
});
uni.onSocketOpen(function (res) {
  console.log("WebSocket 连接已打开！");
});

3.3. `uni.onSocketError(CALLBACK)`

监听 WebSocket 错误。

警告

已废弃，使用 SocketTask 的 onError 替换。

平台兼容性:

抖音小程序不支持；

3.3.1. `onSocketError` 兼容性

HarmonyOS
HBuilderX 4.23

3.3.2. 示例代码

JavaScript

uni.connectSocket({
  url: "wss://www.example.com/socket",
});
uni.onSocketOpen(function (res) {
  console.log("WebSocket 连接已打开！");
});
uni.onSocketError(function (res) {
  console.log("WebSocket 连接打开失败，请检查！");
});

3.4. `uni.sendSocketMessage(OBJECT)`

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

警告

已废弃，使用 SocketTask 的 send 替换。

平台兼容性：

抖音小程序不支持；

3.4.1. `sendSocketMessage` 兼容性

HarmonyOS
HBuilderX 4.23

3.4.2. `OBJECT` 参数说明

参数名	类型	必填	说明
`data`	`String`/`ArrayBuffer`	是	需要发送的内容
`success`	`Function`	否	接口调用成功的回调函数
`fail`	`Function`	否	接口调用失败的回调函数
`complete`	`Function`	否	接口调用结束的回调函数（调用成功、失败都会执行）

3.4.3. 注意事项

出于性能的权衡，在 Android 端底层实现上发送队列占用的内存不能超过 16M，一旦超过将导致连接被关闭。

3.4.4. 示例代码

JavaScript

var socketOpen = false;
var socketMsgQueue = [];

uni.connectSocket({
  url: "wss://www.example.com/socket",
});

uni.onSocketOpen(function (res) {
  socketOpen = true;
  for (var i = 0; i < socketMsgQueue.length; i++) {
    sendSocketMessage(socketMsgQueue[i]);
  }
  socketMsgQueue = [];
});

function sendSocketMessage(msg) {
  if (socketOpen) {
    uni.sendSocketMessage({
      data: msg,
    });
  } else {
    socketMsgQueue.push(msg);
  }
}

3.5. `uni.onSocketMessage(CALLBACK)`

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

警告

已废弃，使用 SocketTask 的 onMessage 替换。

平台兼容性：

抖音小程序不支持；

3.5.1. `onSocketMessage` 兼容性

HarmonyOS
HBuilderX 4.23

3.5.2. `CALLBACK` 返回参数

参数	类型	说明
`data`	`String`/`ArrayBuffer`	服务器返回的消息

3.5.3. 示例代码

JavaScript

uni.connectSocket({
  url: "wss://www.example.com/socket",
});

uni.onSocketMessage(function (res) {
  console.log("收到服务器内容：" + res.data);
});

3.6. `uni.closeSocket(OBJECT)`

关闭 WebSocket 连接。

警告

已废弃，使用 SocketTask 的 close 替换。

平台兼容性：

抖音小程序不支持；

3.6.1. `closeSocket` 兼容性

HarmonyOS
HBuilderX 4.23

3.6.2. `OBJECT` 参数说明

参数名	类型	必填	说明
`code`	`Number`	否	一个数字值表示关闭连接的状态号，表示连接被关闭的原因。如果这个参数没有被指定，默认的取值是 `1000`（表示正常连接关闭）
`reason`	`String`	否	一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于 123 字节的 UTF-8 文本（不是字符）
`success`	`Function`	否	接口调用成功的回调函数
`fail`	`Function`	否	接口调用失败的回调函数
`complete`	`Function`	否	接口调用结束的回调函数（调用成功、失败都会执行）

3.7. `uni.onSocketClose(CALLBACK)`

监听 WebSocket 关闭。

警告

已废弃，使用 SocketTask 的 onClose 替换。

平台兼容性：

抖音小程序不支持；

3.7.1. `onSocketClose` 兼容性

HarmonyOS
HBuilderX 4.23

3.7.2. 示例代码

JavaScript

uni.connectSocket({
  url: "wss://www.example.com/socket",
});

// 注意这里有时序问题，
// 如果 uni.connectSocket 还没回调 uni.onSocketOpen，而先调用 uni.closeSocket，那么就做不到关闭 WebSocket 的目的。
// 必须在 WebSocket 打开期间调用 uni.closeSocket 才能关闭。
uni.onSocketOpen(function () {
  uni.closeSocket();
});

uni.onSocketClose(function (res) {
  console.log("WebSocket 已关闭！");
});

4. `SocketTask`

SocketTask 由 uni.connectSocket() 接口创建。

4.1. 平台差异说明

支付宝小程序、抖音小程序，没有明确的文档来具体说明这个对象，而是指向了 Web Websocket 对象。

4.2. `SocketTask.onMessage(CALLBACK)`

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

4.2.1. `CALLBACK` 参数

WebSocket 接受到服务器的消息事件的回调函数。

回调函数中 Object 的参数：

属性	类型	说明
`data`	`String`/`ArrayBuffer`	服务器返回的消息

4.3. `SocketTask.send(OBJECT)`

通过 WebSocket 连接发送数据。

4.3.1. `OBJECT` 参数

属性	类型	是否必填	说明
`data`	`String`/`ArrayBuffer`	是	需要发送的内容
`success`	`Function`	否	接口调用成功的回调函数
`fail`	`Function`	否	接口调用失败的回调函数
`complete`	`Function`	否	接口调用结束的回调函数（调用成功、失败都会执行）

4.4. `SocketTask.close(OBJECT)`

关闭 WebSocket 连接。

4.4.1. `OBJECT` 参数

属性	类型	默认值	是否必填	说明
`code`	`Number`	`1000`（表示正常关闭连接）	否	一个数字值表示关闭连接的状态号，表示连接被关闭的原因
`reason`	`String`		否	一个可读的字符串，表示连接被关闭的原因
`success`	`Function`		否	接口调用成功的回调函数
`fail`	`Function`		否	接口调用失败的回调函数
`complete`	`Function`		否	接口调用结束的回调函数（调用成功、失败都会执行）

4.5. `SocketTask.onOpen(CALLBACK)`

监听 WebSocket 连接打开事件。

4.5.1. `CALLBACK` 参数

WebSocket 连接打开事件的回调函数。

回调函数中的 Object 参数：

属性	类型	说明
`data`	`String`/`ArrayBuffer`	服务器返回的消息

4.6. `SocketTask.onClose(CALLBACK)`

监听 WebSocket 连接关闭事件。

4.6.1. `CALLBACK` 参数

WebSocket 连接关闭事件的回调函数。

回调函数中的 Object 参数：

属性	类型	说明	平台兼容性
`code`	`Number`	一个数字值表示关闭连接的状态号，表示连接被关闭的原因	HBuilderX（3.7.12+）
`reason`	`String`	一个可读的字符串，表示连接被关闭的原因	HBuilderX（3.7.12+）

4.7. `SocketTask.onError(CALLBACK)`

监听 WebSocket 错误事件。

4.7.1. `CALLBACK` 参数

WebSocket 错误事件的回调函数。

回调函数中的 Object 参数：

属性	类型	说明
`errMsg`	`String`	错误信息

UniApp 网络 ​

1. 发起请求 ​

1.1. uni.request(OBJECT) ​

1.1.1. request 兼容性 ​

1.1.2. OBJECT 参数说明 ​

1.1.2.1. method 有效值 ​

1.1.2.2. success 返回参数说明 ​

1.1.2.3. data 数据说明 ​

1.1.3. 返回值 ​

1.1.3.1. RequestTask ​

1.1.4. 注意事项 ​

1.2. uni.configMTLS(OBJECT) ​

1.2.1. OBJECT 参数说明 ​

1.2.1.1. certificate 参数说明 ​

1.2.1.2. callbackObject 参数说明 ​

2. 上传、下载 ​

2.1. uni.uploadFile(OBJECT) ​

2.1.1. uploadFile 兼容性 ​

2.1.2. OBJECT 参数说明 ​

2.1.2.1. files 参数说明 ​

2.1.2.2. success 返回参数说明 ​

2.1.3. 返回值 ​

2.1.3.1. uploadTask 对象的方法列表 ​

onProgressUpdate 返回参数说明 ​

OnProgressUpdateResult 的属性值 ​

2.1.4. 示例 ​

2.2. uni.downloadFile(OBJECT) ​

2.2.1. downloadFile 兼容性 ​

2.2.2. OBJECT 参数说明 ​

2.2.2.1. success 返回参数说明 ​

2.2.3. 返回值 ​

2.2.3.1. downloadTask 对象的方法列表 ​

onProgressUpdate 返回参数说明 ​

OnProgressDownloadResult 的属性值 ​

2.2.4. 示例 ​

3. WebSocket ​

3.1. uni.connectSocket(OBJECT) ​

3.1.1. connectSocket 兼容性 ​

3.1.2. OBJECT 参数说明 ​

3.1.3. 返回值 ​

3.1.3.1. SocketTask 对象的方法列表 ​

SendSocketMessageOptions 的属性值 ​

SendSocketMessageFail 的属性值 ​

CloseSocketOptions 的属性值 ​

OnSocketOpenCallbackResult 的属性值 ​

OnSocketMessageCallbackResult 的属性值 ​

3.1.4. 注意事项 ​

3.2. uni.onSocketOpen(CALLBACK) ​

3.2.1. onSocketOpen 兼容性 ​

3.2.2. CALLBACK 返回参数 ​

3.2.3. 示例代码 ​

3.3. uni.onSocketError(CALLBACK) ​

3.3.1. onSocketError 兼容性 ​

3.3.2. 示例代码 ​

3.4. uni.sendSocketMessage(OBJECT) ​

3.4.1. sendSocketMessage 兼容性 ​

3.4.2. OBJECT 参数说明 ​

3.4.3. 注意事项 ​

3.4.4. 示例代码 ​

3.5. uni.onSocketMessage(CALLBACK) ​

3.5.1. onSocketMessage 兼容性 ​

3.5.2. CALLBACK 返回参数 ​

3.5.3. 示例代码 ​

3.6. uni.closeSocket(OBJECT) ​

3.6.1. closeSocket 兼容性 ​

3.6.2. OBJECT 参数说明 ​

3.7. uni.onSocketClose(CALLBACK) ​

3.7.1. onSocketClose 兼容性 ​

3.7.2. 示例代码 ​

4. SocketTask ​

4.1. 平台差异说明 ​

4.2. SocketTask.onMessage(CALLBACK) ​

4.2.1. CALLBACK 参数 ​

4.3. SocketTask.send(OBJECT) ​

4.3.1. OBJECT 参数 ​

4.4. SocketTask.close(OBJECT) ​

4.4.1. OBJECT 参数 ​

4.5. SocketTask.onOpen(CALLBACK) ​

4.5.1. CALLBACK 参数 ​

4.6. SocketTask.onClose(CALLBACK) ​

UniApp 网络

1. 发起请求

1.1. `uni.request(OBJECT)`

1.1.1. `request` 兼容性

1.1.2. `OBJECT` 参数说明

1.1.2.1. `method` 有效值

1.1.2.2. `success` 返回参数说明

1.1.2.3. `data` 数据说明

1.1.3. 返回值

1.1.3.1. `RequestTask`

1.1.4. 注意事项

1.2. `uni.configMTLS(OBJECT)`

1.2.1. `OBJECT` 参数说明

1.2.1.1. `certificate` 参数说明

1.2.1.2. `callbackObject` 参数说明

2. 上传、下载

2.1. `uni.uploadFile(OBJECT)`

2.1.1. `uploadFile` 兼容性

2.1.2. `OBJECT` 参数说明

2.1.2.1. `files` 参数说明

2.1.2.2. `success` 返回参数说明

2.1.3. 返回值

2.1.3.1. `uploadTask` 对象的方法列表

`onProgressUpdate` 返回参数说明

`OnProgressUpdateResult` 的属性值

2.1.4. 示例

2.2. `uni.downloadFile(OBJECT)`

2.2.1. `downloadFile` 兼容性

2.2.2. `OBJECT` 参数说明

2.2.2.1. `success` 返回参数说明

2.2.3. 返回值

2.2.3.1. `downloadTask` 对象的方法列表

`onProgressUpdate` 返回参数说明

`OnProgressDownloadResult` 的属性值

2.2.4. 示例

3. WebSocket

3.1. `uni.connectSocket(OBJECT)`

3.1.1. `connectSocket` 兼容性

3.1.2. `OBJECT` 参数说明

3.1.3. 返回值

3.1.3.1. `SocketTask` 对象的方法列表

`SendSocketMessageOptions` 的属性值

`SendSocketMessageFail` 的属性值

`CloseSocketOptions` 的属性值

`OnSocketOpenCallbackResult` 的属性值

`OnSocketMessageCallbackResult` 的属性值

3.1.4. 注意事项

3.2. `uni.onSocketOpen(CALLBACK)`

3.2.1. `onSocketOpen` 兼容性

3.2.2. `CALLBACK` 返回参数

3.2.3. 示例代码

3.3. `uni.onSocketError(CALLBACK)`

3.3.1. `onSocketError` 兼容性

3.3.2. 示例代码

3.4. `uni.sendSocketMessage(OBJECT)`

3.4.1. `sendSocketMessage` 兼容性

3.4.2. `OBJECT` 参数说明

3.4.3. 注意事项

3.4.4. 示例代码

3.5. `uni.onSocketMessage(CALLBACK)`

3.5.1. `onSocketMessage` 兼容性

3.5.2. `CALLBACK` 返回参数

3.5.3. 示例代码

3.6. `uni.closeSocket(OBJECT)`

3.6.1. `closeSocket` 兼容性

3.6.2. `OBJECT` 参数说明

3.7. `uni.onSocketClose(CALLBACK)`

3.7.1. `onSocketClose` 兼容性

3.7.2. 示例代码

4. `SocketTask`

4.1. 平台差异说明

4.2. `SocketTask.onMessage(CALLBACK)`

4.2.1. `CALLBACK` 参数

4.3. `SocketTask.send(OBJECT)`

4.3.1. `OBJECT` 参数

4.4. `SocketTask.close(OBJECT)`

4.4.1. `OBJECT` 参数

4.5. `SocketTask.onOpen(CALLBACK)`

4.5.1. `CALLBACK` 参数

4.6. `SocketTask.onClose(CALLBACK)`