更新记录

1.0.0（2026-09-17）

• 新增 TCP 客户端与服务端、多连接管理、定向发送、广播和本地地址查询。
• 新增文本、HEX、字节数组收发，以及原始流、分隔符、固定长度和长度前缀四种报文处理方式。
• 新增有限自动重连、连接与接入状态回调、队列限额和明确的发送失败结果。
• 提供 uni-app / uni-app x 示例；HarmonyOS 客户端需 API 12+，完整服务端需 API 20+。
• 首次接入需重新制作并安装 Android 自定义基座，并重新打包 iOS / HarmonyOS。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

lizhao-tcp-pro

介绍

为 uni-app / uni-app x 提供 TCP 客户端与服务端，用同一套 API 连接设备、接收外部连接、管理多条会话，并按业务协议处理粘包、拆包和断线重连。

功能特色

适合哪些场景

TCP 是字节流。插件处理传输和报文边界，设备指令、登录认证、业务应答及去重规则仍由你的协议决定。

下载与导入

1. 使用 HBuilderX 将插件导入项目，保留完整的 uni_modules/lizhao-tcp-pro。
2. 页面从插件根目录导入：

import * as Tcp from '@/uni_modules/lizhao-tcp-pro'

uni-app 使用 .vue 页面，uni-app x 使用 .uvue 与 lang="uts"。完整操作示例分别见 uni-app 示例 和 uni-app x 示例。

5 分钟跑通：客户端与服务端互发消息

先在本机监听 127.0.0.1:19090，监听成功后连接，连接成功后发送。服务端只回复一次，客户端只显示结果。若 getTcpCapabilities().server.supported 为 false，请使用后文“连接一个设备”的外部服务端示例。

uni-app

将以下内容放入一个已注册的 .vue 页面，点击按钮。

<template><view><button @tap="run">开始通信</button><text>{{ message }}</text></view></template>
<script>
import * as Tcp from '@/uni_modules/lizhao-tcp-pro'
export default {
  data() { return { message: '', leaving: false } },
  onUnload() {
    this.leaving = true
    Tcp.closeTcpConnection({ connectionId: 'demo-client', complete: () => {
      Tcp.stopTcpServer({ serverId: 'demo-server' })
    } })
  },
  methods: {
    run() {
      const fail = e => { this.message = e.errMsg }
      if (!Tcp.getTcpCapabilities().server.supported) { this.message = '本系统请连接外部 TCP 服务端'; return }
      Tcp.startTcpServer({ serverId: 'demo-server', port: 19090, dataFormat: 'text',
        frame: { mode: 'delimiter', delimiterText: '\n' }, fail,
        onData: e => Tcp.sendTcpData({ connectionId: e.connectionId, dataFormat: 'text', text: '收到\n', fail }),
        success: () => {
          if (this.leaving) return
          Tcp.connectTcp({ connectionId: 'demo-client', host: '127.0.0.1', port: 19090, dataFormat: 'text',
            frame: { mode: 'delimiter', delimiterText: '\n' }, fail,
            onData: e => { this.message = e.text ?? '' },
            success: () => { if (!this.leaving) Tcp.sendTcpData({ connectionId: 'demo-client', dataFormat: 'text', text: '你好\n', fail }) }
          })
        }
      })
    }
  }
}
</script>

uni-app x

调用顺序相同，UTS 页面示例如下。

<template><view><button @tap="run">开始通信</button><text>{{ message }}</text></view></template>
<script setup lang="uts">
import * as Tcp from '@/uni_modules/lizhao-tcp-pro'
const message = ref('')
let leaving = false
function fail(e: Tcp.TcpFail) { message.value = e.errMsg ?? '通信失败' }
function run() {
  if (!Tcp.getTcpCapabilities().server.supported) { message.value = '本系统请连接外部 TCP 服务端'; return }
  Tcp.startTcpServer({ serverId: 'demo-server', port: 19090, dataFormat: 'text',
    frame: { mode: 'delimiter', delimiterText: '\n' }, fail,
    onData: (e) => { Tcp.sendTcpData({ connectionId: e.connectionId, dataFormat: 'text', text: '收到\n', fail }) },
    success: () => {
      if (leaving) return
      Tcp.connectTcp({ connectionId: 'demo-client', host: '127.0.0.1', port: 19090, dataFormat: 'text',
        frame: { mode: 'delimiter', delimiterText: '\n' }, fail,
        onData: (e) => { message.value = e.text ?? '' },
        success: () => { if (!leaving) Tcp.sendTcpData({ connectionId: 'demo-client', dataFormat: 'text', text: '你好\n', fail }) }
      })
    }
  })
}
onUnload(() => {
  leaving = true
  Tcp.closeTcpConnection({ connectionId: 'demo-client', complete: () => { Tcp.stopTcpServer({ serverId: 'demo-server' }) } })
})
</script>

核心配置

接入方式选择

从基础到进阶：按业务模块使用

下面的片段均使用前面的 Tcp 根导入。示例的地址、端口、分隔符须替换为实际设备协议。

模块一：连接一个设备

当设备已经监听 TCP 端口时，App 作为客户端。等待成功后再发送。

Tcp.connectTcp({ connectionId: 'meter', host: '192.168.1.50', port: 9000,
  dataFormat: 'hex', onData: (e) => { console.log('设备返回', e.hex) },
  success: () => { Tcp.sendTcpData({ connectionId: 'meter', dataFormat: 'hex', hex: '01 03 00 00', fail: (e) => { console.log('发送失败', e.errMsg) } }) },
  fail: (e) => { console.log('连接失败', e.errCode, e.errMsg) }
})

模块二：App 接收外部连接

需要同一局域网的设备连接 App 时，显式监听 0.0.0.0。设备应连接手机的局域网 IP，不能连接 0.0.0.0。

Tcp.startTcpServer({ serverId: 'gateway', host: '0.0.0.0', port: 19090,
  dataFormat: 'text', frame: { mode: 'delimiter', delimiterText: '\n' },
  onConnection: (e) => { console.log('设备接入', e.connectionId, e.remoteAddress) },
  onData: (e) => { console.log('设备上报', e.connectionId, e.text) },
  onClientClose: (e) => { console.log('设备离开', e.connectionId, e.reason) },
  fail: (e) => { console.log('监听失败', e.errMsg) }
})

模块三：文本、HEX 和字节收发

向已就绪的连接发送数据，每次只传与 dataFormat 对应的一个载荷字段。HEX 可包含字节间空白；数组元素必须是 0–255 的整数。

Tcp.sendTcpData({ connectionId: 'meter', dataFormat: 'text', text: 'STATUS\n', fail: (e) => { console.log('发送失败', e.errMsg) } })
Tcp.sendTcpData({ connectionId: 'meter', dataFormat: 'hex', hex: 'AA 55 00 FF', fail: (e) => { console.log('发送失败', e.errMsg) } })
Tcp.sendTcpData({ connectionId: 'meter', dataFormat: 'bytes', bytes: [170, 85, 0, 255], fail: (e) => { console.log('发送失败', e.errMsg) } })

接收事件始终提供 bytes 和大写 hex。选择 text 后，合法 UTF-8 还会提供 text；非法 UTF-8 的 text 为 null，原字节仍保留。raw 模式会保留跨读取的 UTF-8 半字符。

模块四：多连接独立管理

为不同设备使用不同 ID，定向关闭只作用于指定实例。

Tcp.connectTcp({ connectionId: 'device-a', host: '192.168.1.51', port: 9000, fail: (e) => { console.log('A 连接失败', e.errMsg) } })
Tcp.connectTcp({ connectionId: 'device-b', host: '192.168.1.52', port: 9000, fail: (e) => { console.log('B 连接失败', e.errMsg) } })
Tcp.closeTcpConnection({ connectionId: 'device-a', reason: '结束本次操作' })

模块五：处理粘包与拆包

根据对方协议选择接收方式。sendTcpData 始终发送原始载荷，不会因连接配置了 frame 就自动补头或补分隔符。

要生成“2 字节大端长度头 + UTF-8 正文”，使用同步构帧结果：

const encoded = Tcp.encodeTcpFrame({ dataFormat: 'text', text: '设备状态',
  frame: { mode: 'lengthPrefix', lengthPrefixBytes: 2, byteOrder: 'big' }
})
if (encoded.ok) {
  Tcp.sendTcpData({ connectionId: 'meter', dataFormat: 'bytes', bytes: encoded.bytes,
    fail: (e) => { console.log('发送失败', e.errMsg) } })
} else { console.log('构帧失败', encoded.error?.errMsg) }

对应接收端也需配置相同长度头。delimiter 模式构帧会在正文后追加分隔符，正文中不允许再含完整分隔符；fixedLength 正文长度必须精确相等；raw 保留正文。

模块六：断线后恢复连接

适用于网络偶发中断。首次 success / fail / complete 只结算一次，之后的重连进度由持续事件报告。

Tcp.connectTcp({ connectionId: 'stable-device', host: '192.168.1.50', port: 9000,
  reconnect: { enabled: true, maxAttempts: 5, initialDelayMs: 1000, maxDelayMs: 30000 },
  onState: (e) => { console.log('连接状态', e.state, e.reconnectAttempt) },
  onError: (e) => { console.log('运行期错误', e.errMsg) },
  fail: (e) => { console.log('首次连接失败', e.errMsg) }
})

主动关闭会取消重连。断开时未完成的发送逐项失败，恢复后不会自动重发，以免重复执行设备指令。

模块七：广播与关闭接入连接

服务端已启动后，广播给调用时存在的所有接入连接。关闭单个接入终端时使用该终端的 connectionId。

Tcp.broadcastTcpData({ serverId: 'gateway', dataFormat: 'text', text: 'PING\n',
  success: (r) => { console.log('广播完成', r.successCount) },
  fail: (e) => { console.log('广播存在失败', e.details) }
})
Tcp.getTcpServerConnections({ serverId: 'gateway', success: (r) => {
  if (r.connections.length > 0) Tcp.closeTcpConnection({ connectionId: r.connections[0].connectionId, reason: '结束接入' })
}, fail: (e) => { console.log('查询失败', e.errMsg) } })

模块八：查看连接与本机地址

用于展示就绪状态、连接数和可供其他设备访问的地址。查询结果是当前快照。

Tcp.getTcpConnectionInfo({ connectionId: 'meter', success: (r) => { console.log('连接', r.state, r.sentBytes, r.receivedBytes) }, fail: (e) => { console.log(e.errMsg) } })
Tcp.getTcpServerInfo({ serverId: 'gateway', success: (r) => { console.log('监听', r.address, r.port, r.connectionCount) }, fail: (e) => { console.log(e.errMsg) } })
Tcp.getLocalAddresses({ family: 'ipv4', includeLoopback: false, success: (r) => { console.log('本机地址', r.addresses) }, fail: (e) => { console.log(e.errMsg) } })

模块九：页面退出时释放

让会话归属清晰的页面或业务模块管理。结束时先关闭客户端，再停止该模块创建的服务端；停止服务端会一并关闭其接入连接。

Tcp.closeTcpConnection({ connectionId: 'meter', reason: '页面退出', complete: () => {
  Tcp.stopTcpServer({ serverId: 'gateway', reason: '页面退出' })
} })

API 用途速查

除两个同步方法外，API 返回 void，异步结果通过 success / fail / complete 接收。

参数说明与分包、重连配置

连接与监听

基本字段见“核心配置”；以下为增强字段。

插件总活动连接最多 64 条（含外连和接入），监听器最多 8 个。ID 长度为 1–128 且不能全是空白；host 长度不超过 253。

发送、广播与同步构帧

单次发送正文不超过 4 MiB。发送队列最多 256 项且总字节不超过 4 MiB（含正在发送项），超限的新命令失败。文本或字节数组可为空；HEX 至少一个完整字节。

分帧配置 frame

不要混入其他模式专属字段。长度头允许正文长度为 0；一字节头最大 255，两字节头最大 65535，仍受 maxFrameBytes 限制。

重连配置 reconnect

参数错误、协议错误、缓冲溢出与主动关闭不会重连。可重试网络错误仍受次数限制。

本地地址查询

回调说明

连接状态为 idle → connecting → ready；重试进入 reconnect-wait，最终关闭为 closing → closed。服务端状态为 idle → starting → listening → stopping → stopped。每次新尝试的 generation 用于区分迟到结果。页面离开时显式关闭会话，停止后持续回调随资源释放。

支持平台

推荐 HBuilderX 5.24 或更高版本。App 首次接入或更新原生部分后，需重新制作包含插件的 Android 自定义基座，并重新打包 iOS / HarmonyOS；Android 与 HarmonyOS 项目需合并插件声明的网络权限。

返回值说明

广播目标数为 0 时成功返回空结果。任何目标失败时走 fail，汇总仍位于 error.details；bytesWritten=-1 或 deliveryUnknown=true 表示无法确认远端交付，不能直接认定“没发出去”。

错误码说明

注意事项与常见错误

• sendTcpData.success 仅表示本地写操作完成。需要确认设备执行结果时，必须等待业务应答并自行设置请求标识与去重规则。
• 对方一次发送可能被拆成多次读取，多次发送也可能合并。双方应明确分隔符、固定长度或长度头；不能靠读取块大小识别报文。
• 连接参数和载荷在调用时保存副本，调用后修改原对象不会更新当前会话；修改协议配置请关闭后重建。
• 127.0.0.1 只能本机访问；局域网监听应使用 0.0.0.0 或指定本机网卡地址。网卡列表不保证远端可达，仍受路由、热点隔离、防火墙和系统权限影响。
• 插件提供普通 TCP，不提供 TLS、UDP、WebSocket、应用层心跳或设备协议解析。涉及敏感数据时应使用适合业务的加密与认证协议。
• 自动重连和系统 TCP keep-alive 不保证 App 在后台持续运行，应用被系统挂起或结束后应由业务重新建立连接。
• 关闭同一个不存在的合法 ID 会幂等成功；查询不存在的 ID 则失败。关闭过程中已接受的命令会先结算，后报告关闭完成。
• 默认有限额保护。提高帧大小时同步调整接收缓冲；不要在 onData 中长时间阻塞，也不要让收发双方无限自动互相回复。
• 插件只处理调用方指定连接上的数据，不自行上传、持久化或记录业务正文。

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。