uni.connectSocket 是 uni-app 框架提供的一个用于创建 WebSocket 连接的跨平台 API

uni.connectSocket 是 uni-app 框架提供的一个用于创建 WebSocket 连接的跨平台 API。它封装了不同端（如 H5、App、微信小程序等）底层的实现差异，使开发者能够使用统一的接口实现客户端与服务器之间的全双工实时通信。

核心技术特点

跨平台兼容：屏蔽了 iOS、Android、各小程序及 H5 的底层差异，开发者无需针对不同平台编写不同的 WebSocket 代码。
SocketTask 实例管理 ：调用 uni.connectSocket 会返回一个 SocketTask 对象，开发者需通过该实例来管理连接状态、发送消息和监听事件。这种方式支持多连接管理，避免了全局单例的局限性。
持久化双向通信：与传统的 HTTP 请求不同，WebSocket 建立后会保持长连接，服务器可以主动向客户端推送数据，非常适合即时通讯、实时行情、协同编辑等低延迟场景。

如何使用

1. 基础用法：创建连接与监听事件

复制代码

// 1. 创建 WebSocket 连接
const socketTask = uni.connectSocket({
  url: 'wss://example.com/socket', // 小程序端必须使用 wss 协议
  header: {
    'content-type': 'application/json'
  },
  success: () => console.log('连接请求已发送'),
  fail: (err) => console.error('连接请求失败', err)
});

// 2. 监听连接打开
socketTask.onOpen(() => {
  console.log('WebSocket 连接已打开');
});

// 3. 监听接收服务器消息
socketTask.onMessage((res) => {
  console.log('收到服务器消息:', res.data);
});

// 4. 监听连接错误与关闭
socketTask.onError((err) => console.error('连接发生错误:', err));
socketTask.onClose(() => console.log('连接已关闭'));

2. 发送数据与关闭连接

复制代码

// 必须在 onOpen 回调触发后，才能安全地发送消息
socketTask.send({
  data: JSON.stringify({ type: 'greeting', content: 'Hello Server!' }),
  success: () => console.log('消息发送成功'),
  fail: (err) => console.error('消息发送失败', err)
});

// 主动关闭连接
socketTask.close({
  code: 1000,
  reason: '正常关闭'
});

💡 生产环境最佳实践

在实际的商业项目开发中，直接使用 uni.connectSocket 往往不够健壮，通常需要构建一套完整的生命周期管理机制：

心跳保活机制 ：由于 NAT 网关或防火墙可能会在空闲一段时间后断开连接，客户端需要定期（如每 25 秒）发送心跳包（如 ping），服务端回复 pong，以维持长连接的活跃状态。
智能重连策略 ：当网络波动导致连接断开时，不应采用固定频率重试，而应实现指数退避算法 （如 1s、2s、4s、8s 递增重试），并配合 uni.getNetworkType 监听网络状态，实现"有网才重连"，防止雪崩效应。
消息队列与离线缓存 ：在连接未就绪或断连期间，业务代码可能会调用发送方法。此时应将消息暂存至内存队列，待 onOpen 触发后再按序重发，保障数据的最终一致性。
后台保活与状态同步 ：在 App 端，iOS 进入后台后系统会挂起网络连接，而部分 Android 厂商的省电策略可能导致"假连接"。建议在应用生命周期（如 onHide）中主动处理连接状态，并在重新回到前台时校验连接有效性。