更新记录

1.0.0（2026-10-31）

初始版本：WebSocket / TCP / UDP 多会话（Android / iOS / 鸿蒙）

• 事件：onOpen / onMessage / onClose / onError；文本 utf8 + 二进制 base64
• Android：OkHttp + Socket + DatagramSocket；iOS：URLSessionWebSocket + NWConnection；鸿蒙：@kit.NetworkKit（含 ohos.permission.INTERNET）
• JS 托管 createManagedSocket：帧协议（length2 / length4 / delimiter）、心跳、空闲超时、自动重连、状态机、发送队列
• TCP 原生收包统一 base64；组件 <zv-socket>

平台兼容性

uni-app(4.41)

zv-socket

原生 Socket：WebSocket + TCP + UDP（Android / iOS / 鸿蒙）+ JS 托管层（帧协议 / 心跳 / 重连 / 发送队列）。

本人设备有限，没有做全部测试，请先试用，确认正常后再购买

H5 为桩（9030001）。App 需 自定义调试基座 / 云打包。

推荐：托管会话 createManagedSocket

import { createManagedSocket } from '@/uni_modules/zv-socket/js_sdk'

const sock = createManagedSocket({
  type: 'tcp',
  host: '192.168.1.10',
  port: 9000,
  // 帧：none | length2 | length4 | delimiter
  frameMode: 'length4',
  delimiter: '\n',
  heartbeatInterval: 15000,
  heartbeatPayload: 'ping',
  idleTimeout: 45000,
  autoReconnect: true,
  reconnectDelay: 1000,
  reconnectMaxDelay: 30000,
  maxRetry: 10,          // -1 无限
  maxQueue: 200,
  onState: (s) => console.log(s), // connecting|connected|reconnecting|closed
  onOpen: (e) => {},
  onMessage: (e) => console.log(e.data, e.framed),
  onClose: (e) => console.log(e.active),
  onError: (e) => {},
  onReconnect: ({ attempt, delay }) => {}
})

sock.connect()
sock.send('hello')   // 未连上先入队，连上后冲刷
sock.close()         // 主动关闭，不再重连

参数说明

帧协议（主要对 TCP；粘包/拆包）

frameMode 取值：

• none：不拆帧。TCP 底层收包是 base64 字节流，托管层会尽量解成 utf8 文本块 再 onMessage；发送也不加长度头。适合「对方发的就是文本块」或你自己在业务里拼。
• length2：每帧前 2 字节 大端 无符号长度（payload 最长 65535），再跟正文。收发都会按此封/拆。
• length4：每帧前 4 字节 大端 无符号长度 + 正文。适合二进制/变长协议。
• delimiter：按 delimiter 切帧（如一行一条 \n）。发送时自动在末尾补分隔符。

示例里写 frameMode:'length4' 同时又写 delimiter：只有改成 'delimiter' 时 delimiter 才有用；length4 下可省略 delimiter。

心跳 / 空闲

说明：心跳只负责「定时往外发」；是否判定对方活着，通常靠 idleTimeout（对方有回包才会刷新空闲计时）。

自动重连 / 发送队列

回调

实例方法

组件：<zv-socket>（easycom），slot 暴露 state / connected / lastMessage 等，方法 connect / send / close。

底层 API（原始）

import {
  createSocket, sendSocket, closeSocket,
  onSocket, offSocket, closeAllSockets
} from '@/uni_modules/zv-socket'

onSocket({
  onOpen: (e) => {},
  onMessage: (e) => console.log(e.encoding, e.data), // TCP 为 base64
  onClose: (e) => {},
  onError: (e) => {}
})

createSocket({ type: 'tcp', host: '192.168.1.10', port: 9000 })
createSocket({ type: 'udp', host: '…', port: 9001, localPort: 0 })
createSocket({ type: 'ws', url: 'ws://192.168.1.10:8080/path' })

sendSocket({ socketId, data: 'hello', encoding: 'utf8' })
sendSocket({ socketId, data: uni.arrayBufferToBase64(buf), encoding: 'base64' })

readyState（底层）

0 连接中 · 1 已连接/已绑定 · 2 关闭中 · 3 已关闭

错误码

9030001 平台不支持 · 9030002 参数错误 · 9030003 连接失败 · 9030004 发送失败 · 9030005 会话不存在 · 9030006 已关闭/空闲超时

注意

• TCP 收包为 encoding:'base64'（保字节流）；文本业务请用 createManagedSocket（frameMode:'none' 会解成 utf8）。
• 鸿蒙需 ohos.permission.INTERNET（插件已声明）。
• UDP onMessage 带 remoteHost / remotePort。
• iOS 明文 ws:// / TCP 可能需 ATS 例外。
• 页面销毁请 close() / closeAllSockets()。

与 Android 行为对照（鸿蒙）