更新记录

1.0.0（2026-05-28）

基础tcp函数导出

平台兼容性

uni-app(3.7.8)

zl-tcp

原生 TCP 通信 UTS 插件，支持 TCP 服务端监听和 TCP 客户端连接，适用于 uni-app x 的 Android / iOS / Harmony App 端。

当前版本采用回调式 API，不使用 Promise。服务端会话 TCPSession 只保存连接信息，发送和关闭指定客户端请通过 server.sendToSession() / server.closeSession() 完成。

平台实现

引入

import {
  createTcpServer,
  createTcpClient,
  type ITcpServer,
  type ITcpClient,
  type TCPServerOptions,
  type TCPClientOptions,
  type TCPSendData,
  type TCPSession,
  type TCPMessage,
  type TCPFail,
  type TCPDataType
} from '@/uni_modules/zl-tcp'

在 script setup lang="uts" 中，如果直接传对象字面量，建议显式声明或断言类型：

server.listen({ port: 8080, dataType: 'text' } as TCPServerOptions, onSuccess, onError)
client.send({ dataType: 'hex', data: 'FF0A1B2C' } as TCPSendData)

基础类型

TCPDataType

type TCPDataType = 'text' | 'hex' | 'byte'

TCPSendData

type TCPSendData = {
  dataType: TCPDataType
  data?: string
  byteData?: number[]
}

发送 text：

{ dataType: 'text', data: 'hello' } as TCPSendData

发送 hex：

{ dataType: 'hex', data: 'FF0A1B2C' } as TCPSendData

发送 byte：

{ dataType: 'byte', byteData: [0xFF, 0x0A, 0x1B, 0x2C] } as TCPSendData

TCPMessage

type TCPMessage = {
  dataType: TCPDataType
  data?: string
  byteData?: number[]
}

dataType 表示本连接接收数据时的解析格式。TCP 本身只传字节，不携带“这是 text/hex/byte”的元信息。需要在业务层区分消息格式时，请自行约定协议，或按原始 byteData 自行格式化。

TCPFail

TCP 服务端

创建服务端

const server = createTcpServer()

listen(options, onSuccess, onError)

启动 TCP 监听。

server.listen(
  { port: 8080, dataType: 'text' } as TCPServerOptions,
  () => {
    console.log('服务端启动成功')
  },
  (err: TCPFail) => {
    console.log('服务端启动失败', err.errCode, err.errMsg)
  }
)

TCPServerOptions

不要在同一个端口重复调用 listen()。如需重新监听，请先调用 server.close()。

监听连接

server.onConnection((session: TCPSession) => {
  console.log('客户端连接', session.sessionId, session.remoteAddress, session.remotePort)
})

server.onDisconnection((session: TCPSession) => {
  console.log('客户端断开', session.sessionId)
})

TCPSession

接收数据

server.onData((session: TCPSession, message: TCPMessage) => {
  if (message.dataType == 'text') {
    console.log('收到 text', message.data)
  } else if (message.dataType == 'hex') {
    console.log('收到 hex', message.data)
  } else {
    console.log('收到 byte', message.byteData)
  }
})

发送到指定客户端

server.sendToSession(
  sessionId,
  { dataType: 'text', data: 'hello client' } as TCPSendData
)

server.sendToSession(
  sessionId,
  { dataType: 'hex', data: 'FF0A1B2C' } as TCPSendData
)

server.sendToSession(
  sessionId,
  { dataType: 'byte', byteData: [0xFF, 0x0A, 0x1B, 0x2C] } as TCPSendData
)

获取在线会话

const sessionIds = server.sessions()
for (let i = 0; i < sessionIds.length; i++) {
  console.log(sessionIds[i])
}

关闭指定客户端

server.closeSession(sessionId)

关闭服务端

server.close()

服务端错误监听

server.onError((err: TCPFail) => {
  console.log('服务端错误', err.errCode, err.errMsg)
})

移除服务端监听

const onData = (session: TCPSession, message: TCPMessage) => {
  console.log(session.sessionId, message)
}

server.onData(onData)
server.offData(onData)

服务端支持：

TCP 客户端

创建客户端

const client = createTcpClient()

connect(options, onSuccess, onError)

连接 TCP 服务端。

client.connect(
  {
    host: '127.0.0.1',
    port: 8080,
    dataType: 'text'
  } as TCPClientOptions,
  (id: string) => {
    console.log('客户端连接成功', id)
  },
  (err: TCPFail) => {
    console.log('客户端连接失败', err.errCode, err.errMsg)
  }
)

TCPClientOptions

监听连接状态

client.onConnect((id: string) => {
  console.log('已连接', id)
})

client.onDisconnect((id: string) => {
  console.log('已断开', id)
})

接收数据

client.onData((message: TCPMessage) => {
  console.log('收到数据', message)
})

发送数据

client.send({ dataType: 'text', data: 'hello server' } as TCPSendData)
client.send({ dataType: 'hex', data: 'AABBCCDD' } as TCPSendData)
client.send({ dataType: 'byte', byteData: [0xAA, 0xBB, 0xCC, 0xDD] } as TCPSendData)

获取连接信息

const id = client.getId()
const state = client.getState()

state 取值：

'disconnected' | 'connecting' | 'connected' | 'disconnecting'

断开连接

client.close()

客户端错误监听

client.onError((err: TCPFail) => {
  console.log('客户端错误', err.errCode, err.errMsg)
})

移除客户端监听

const onMessage = (message: TCPMessage) => {
  console.log(message)
}

client.onData(onMessage)
client.offData(onMessage)

客户端支持：

完整示例

服务端

const server = createTcpServer()

server.onConnection((session: TCPSession) => {
  console.log('连接', session.sessionId)
})

server.onData((session: TCPSession, message: TCPMessage) => {
  console.log('收到', message)
  server.sendToSession(
    session.sessionId,
    { dataType: 'text', data: 'pong' } as TCPSendData
  )
})

server.onError((err: TCPFail) => {
  console.log('错误', err.errMsg)
})

server.listen(
  { port: 8080, dataType: 'text' } as TCPServerOptions,
  () => console.log('监听成功'),
  (err: TCPFail) => console.log('监听失败', err.errMsg)
)

客户端

const client = createTcpClient()

client.onConnect((id: string) => {
  console.log('连接成功', id)
  client.send({ dataType: 'text', data: 'ping' } as TCPSendData)
})

client.onData((message: TCPMessage) => {
  console.log('收到', message)
})

client.onError((err: TCPFail) => {
  console.log('错误', err.errMsg)
})

client.connect(
  { host: '127.0.0.1', port: 8080, dataType: 'text' } as TCPClientOptions,
  (id: string) => console.log('connect success', id),
  (err: TCPFail) => console.log('connect fail', err.errMsg)
)

注意事项

1. TCP 是字节流协议，不自带消息边界。一次 send() 可能被对端拆成多次 onData()，多次 send() 也可能合并到一次 onData()。生产环境建议在业务层增加长度头、分隔符或固定包长协议。
2. TCP 不携带数据格式。text / hex / byte 是插件发送和接收时的编码/解码方式，不是网络协议中的元数据。
3. 同一个端口不能重复监听。重复启动前请先调用 server.close()。
4. Android 标准基座可能无法启用 UTS 插件依赖的原生能力，建议使用自定义基座调试。
5. iOS 真机调试需要使用自定义基座，并确认网络权限、局域网权限等系统配置。