更新记录

1.0.0（2026-07-22）

• 新增 Android、iOS 原生 TCP 客户端。
• 新增 TCP 服务端监听和多客户端管理。
• 新增 UDP 绑定、单播和广播。
• 新增 UTF-8 文本与 Base64 二进制收发。
• 新增连接超时、keep-alive、TCP_NODELAY、地址复用和自动重连配置。
• 新增完整连接状态和错误事件。

平台兼容性

uni-app x(3.8.0)

其他

kongbai-socket

面向 uni-app x App 的 Android、iOS 原生 TCP/UDP 通信插件。插件不依赖第三方网络库，支持客户端、服务端、持续收发、广播和二进制数据。

支持范围

• TCP 客户端连接、持续收发和主动断开。
• TCP 服务端监听、接受多个客户端，并通过 clientId 分别收发和关闭。
• UDP 本地端口绑定、单播、广播和任意目标地址发送。
• UTF-8 文本与 Base64 二进制数据收发。
• 连接超时、TCP keep-alive、TCP_NODELAY、地址复用和接收缓冲区配置。
• TCP 客户端可选自动重连和最大重连次数。
• connecting、connected、listening、accepted、bound、data、sent、closed、error 事件。

仅提供 uni-app x App 的 Android 和 iOS 原生实现；Web、各类小程序和 HarmonyOS 不支持。

平台要求

HBuilderX 要求 4.27.0 及以上，uni-app x 要求 3.7.13 及以上。

首次安装、升级插件或修改原生配置后，需要重新制作自定义调试基座或重新云打包。标准基座不会自动包含新增的原生插件代码。

安装

在 HBuilderX 的插件市场导入本插件，或将 kongbai-socket 目录放入项目的 uni_modules 目录。

基础 API

import {
  createKBSocket,
  startKBSocket,
  stopKBSocket,
  destroyKBSocket,
  sendKBSocketText
} from '@/uni_modules/kongbai-socket'

const socketId = createKBSocket({
  type: 'tcp',
  host: '192.168.1.20',
  port: 9000,
  connectTimeout: 5000,
  autoReconnect: true,
  reconnectDelay: 3000,
  maxReconnectAttempts: 5
}, (event) => {
  if (event['event'] == 'connected') {
    sendKBSocketText(socketId, 'hello')
  } else if (event['event'] == 'data') {
    console.log('收到文本:', event['text'] as string)
    console.log('收到 Base64:', event['base64'] as string)
  } else if (event['event'] == 'error') {
    console.error(event['code'], event['message'])
  }
})

startKBSocket(socketId)

createKBSocket 只创建内存中的 Socket，必须调用 startKBSocket 才会连接、监听或绑定 UDP。startKBSocket 返回 true 表示启动任务已提交，不代表连接已经成功；连接结果通过事件返回。

使用完成后调用 stopKBSocket(socketId) 和 destroyKBSocket(socketId)。

TCP 客户端

const clientId = createKBSocket({
  type: 'tcp',
  role: 'client',
  host: '192.168.1.20',
  port: 9000,
  tcpNoDelay: true,
  keepAlive: true
}, (event) => {
  switch (event['event']) {
    case 'connected':
      sendKBSocketText(clientId, 'ready')
      break
    case 'data':
      const base64 = event['base64'] as string
      break
    case 'closed':
      console.log('TCP 已关闭')
      break
    case 'error':
      console.error(event['code'], event['message'])
      break
  }
})
startKBSocket(clientId)

TCP 客户端的 host 和 port 是必填项。服务端协议需要由业务层定义消息边界，例如固定长度、换行符或长度前缀；插件不会自行拼包或拆包。

TCP 服务端

const serverId = createKBSocket({
  type: 'tcp',
  role: 'server',
  localHost: '0.0.0.0',
  port: 9000,
  backlog: 32
}, (event) => {
  const name = event['event'] as string
  if (name == 'accepted') {
    const clientId = event['clientId'] as string
    sendKBSocketText(clientId, 'welcome')
  } else if (name == 'data') {
    const clientId = event['id'] as string
    sendKBSocketText(clientId, 'echo:' + (event['text'] as string))
  }
})
startKBSocket(serverId)

服务端收到 accepted 后，clientId 就是该客户端的独立 Socket id。该 id 可以直接传给 sendKBSocketText、sendKBSocketBase64、stopKBSocket 和 destroyKBSocket。客户端数据事件的 id 也是对应的 clientId。

服务端使用完成后调用 stopKBSocket(serverId) 和 destroyKBSocket(serverId)，已接受的客户端连接会一并关闭。

UDP 单播和广播

const udpId = createKBSocket({
  type: 'udp',
  localHost: '0.0.0.0',
  localPort: 9001,
  broadcast: true,
  bufferSize: 65507
}, (event) => {
  if (event['event'] == 'bound') {
    sendKBSocketText(udpId, 'discover', '255.255.255.255', 9001)
    sendKBSocketBase64(udpId, 'AAECAwQ=', '192.168.1.20', 9001)
  } else if (event['event'] == 'data') {
    console.log('UDP 来源:', event['remoteHost'], event['remotePort'])
    console.log('UDP 内容:', event['text'])
  }
})
startKBSocket(udpId)

UDP 接收端需要使用 localPort 绑定端口。localPort 传 0 时由系统分配临时端口，实际端口可从 bound 事件的 remotePort 字段读取。UDP 单个数据报应控制在网络 MTU 或平台允许的最大数据报范围内，插件不会拆分和重组数据报。

API 说明

createKBSocket(options, handler?)

创建 Socket 并返回唯一 id。此方法不会建立连接、开始监听或绑定 UDP，必须继续调用 startKBSocket(id)。

handler 用于接收 Socket 事件，会在 Socket 生命周期内持续触发。调用 destroyKBSocket(id) 后不再接收该 Socket 的事件。

生命周期方法

状态方法

getKBSocketState(id) 返回当前状态对象。Socket 不存在时返回 { id, state: 'missing' }。

const state = getKBSocketState(socketId)

状态对象包含 id、type、role、state、host、port、localPort 和 reconnectAttempts。state 为 connected 或 closed。

KBSocketOptions

发送方法

sendKBSocketText(id, text, host?, port?) 使用 UTF-8 编码发送文本。

sendKBSocketBase64(id, base64, host?, port?) 将 Base64 解码为原始字节后发送，适合图片、二进制协议和非 UTF-8 数据。

两个方法的返回值只表示本地 Socket 是否已接受本次写入；对端是否处理成功需要由业务协议确认。发送成功会触发 sent，失败会触发 error。

事件

每个事件都包含 event、id、type、role 和 timestamp。timestamp 为毫秒时间戳。

data 事件的 base64 是原始字节的 Base64 编码，text 是按 UTF-8 解码的字符串；非 UTF-8 数据的 text 为空，应使用 base64 处理。TCP 数据按底层读取结果回调，不提供消息边界；UDP 每个 data 事件对应一个数据报。

remoteHost 和 remotePort 在 TCP 中表示对端地址，在 UDP data 事件中表示数据报来源；bound 事件中的 remotePort 表示实际本地端口。

常见错误码包括 connect_failed、listen_failed、accept_failed、bind_failed、receive_failed、read_failed、send_failed 和 invalid_base64。

iOS 局域网说明

插件已声明 NSLocalNetworkUsageDescription。如果宿主项目有自己的 Info.plist 合并配置，应保留相同用途说明。iOS 模拟器的网络行为与真机不同，建议使用真机验证局域网设备、广播和端口复用。

生命周期与安全

• Socket 的连接、监听、接收和发送运行在原生后台线程，事件回调回到主线程；不要在回调中执行长时间阻塞任务。
• 页面销毁或 App 退出前应调用 stopKBSocket 和 destroyKBSocket；不再使用时可调用 closeAllKBSockets。
• 插件不做 TLS。需要加密传输时，应在业务层使用 TLS 代理或另行接入原生 TLS 能力，不要在明文 Socket 上传输敏感凭据。
• 插件不会持久化、上传或缓存网络数据；事件中的数据只在回调生命周期内交给宿主应用。

版本记录

详见 changelog.md。当前版本为 1.0.0。