更新记录

1.0.0（2026-06-27） 下载此版本

初次提交

平台兼容性

uni-app x(5.07)

laoqianjunzi-tcp

laoqianjunzi-tcp 是一个面向 uni-app x 的 TCP 通信插件，提供以下两类能力：

• TCP 服务端监听、会话管理、单播与广播发送
• TCP 客户端连接、链路管理、消息发送与回调接收

插件面向当前版本 API 设计，文档只说明当前导出的类型、类与调用方式，不包含旧插件说明，也不包含旧 API 兼容层。

适用场景

• 局域网设备发现后的 TCP 指令收发
• 与网关、控制器、工控设备建立长连接
• 在 App 端同时承担 TCP 服务端与 TCP 客户端角色
• 在调试阶段快速验证 text、hex、byte 三种负载格式

能力概览

服务端能力

• TcpServerService.start() 启动监听
• TcpServerService.listClients() 获取在线会话快照
• TcpServerService.deliver() 向单个会话发送
• TcpServerService.broadcast() 向全部在线会话广播
• TcpServerService.dropClient() 主动断开指定会话
• TcpServerService.stop() / stopWithResult() 停止监听

客户端能力

• TcpClientService.connect() 建立 TCP 连接
• TcpClientService.listLinks() 获取当前连接列表
• TcpClientService.getLink() 获取指定链路详情
• TcpClientService.push() 向指定链路发送数据
• TcpClientService.disconnect() 关闭单条链路
• TcpClientService.disconnectAll() 关闭全部链路

通用能力

• setTraceLevel() 控制插件调试日志
• 统一 TcpResult 返回结构，方便页面侧处理结果码与提示文案
• 统一 TcpPayloadKind 负载模型，支持 text、hex、byte

平台支持

Web 端不会建立真实 TCP 服务端或客户端连接，适合先联调页面逻辑、参数校验和回调链路，不适合验证真实网络通信。

安装与引入

将插件放入项目 uni_modules 目录后，可直接通过模块入口引入：

import {
  TcpClientService,
  TcpServerService,
  setTraceLevel,
  type TcpClientHooks,
  type TcpLinkMessage,
  type TcpPeerOptions,
  type TcpServerHooks,
  type TcpServerOptions,
  type TcpSessionPacket
} from "@/uni_modules/laoqianjunzi-tcp"

核心概念

1. 服务端与会话

• 一个 TcpServerService 实例对应一个监听服务
• 每个接入客户端会形成一个 sessionId
• 服务端单播时通过 targetSessionId 指定目标会话

2. 客户端与链路

• 一个 TcpClientService 实例可同时维护多条外连链路
• 每条链路通过 linkId 标识
• connect() 时传空字符串会自动生成链路 ID

3. 负载格式

插件统一使用 TcpPayloadKind 表示负载格式：

说明：

• text 模式下，text 不能为空
• hex 模式下，使用 text 传输十六进制字符串，推荐只传连续的偶数长度十六进制字符，例如 48656C6C6F
• byte 模式下，使用 bytes 传输 Array<number>，每个元素应在 0 到 255 之间
• 同一条真实链路的收发双方应使用一致的 payloadKind
• hex 模式接收回来的字符串只保证语义一致，不保证大小写一致，业务端应按不区分大小写处理

快速开始

服务端示例

import {
  TcpServerService,
  type TcpIncomingMessage,
  type TcpResult,
  type TcpServerHooks
} from "@/uni_modules/laoqianjunzi-tcp"

const server = new TcpServerService()

const hooks: TcpServerHooks = {
  onClientJoin(session) {
    console.log("join", session.sessionId, session.remoteHost, session.remotePort)
  },
  onMessage(session, packet: TcpIncomingMessage) {
    console.log("message", session.sessionId, packet.payloadKind, packet.text, packet.bytes)
  },
  onClientLeave(session) {
    console.log("leave", session.sessionId)
  },
  onPhaseChange(state) {
    console.log("phase", state.phase)
  },
  onError(result: TcpResult) {
    console.log("server error", result.code, result.message)
  }
}

server.start({
  port: 18897,
  payloadKind: "text",
  keepAlive: true,
  pendingLimit: 50,
  readTimeout: 0,
  receiveBufferSize: 4096,
  sendBufferSize: 4096
}, hooks, (result) => {
  console.log("start result", result.code, result.message)
})

向指定会话发送文本：

server.deliver({
  targetSessionId: "session-1",
  payloadKind: "text",
  text: "hello from server"
}, (result) => {
  console.log("deliver result", result.code, result.message)
})

广播发送：

server.broadcast({
  payloadKind: "hex",
  text: "48656C6C6F20544350"
})

客户端示例

import {
  TcpClientService,
  type TcpClientHooks,
  type TcpLinkMessage,
  type TcpPeerOptions,
  type TcpResult
} from "@/uni_modules/laoqianjunzi-tcp"

const client = new TcpClientService()

const options: TcpPeerOptions = {
  host: "192.168.1.10",
  port: 18897,
  payloadKind: "text",
  keepAlive: true,
  connectTimeout: 3000,
  readTimeout: 0,
  receiveBufferSize: 4096,
  sendBufferSize: 4096
}

const hooks: TcpClientHooks = {
  onOpen(linkId) {
    console.log("open", linkId)
  },
  onMessage(packet) {
    console.log("message", packet.linkId, packet.payloadKind, packet.text, packet.bytes)
  },
  onClose(linkId) {
    console.log("close", linkId)
  },
  onError(linkId, message) {
    console.log("client error", linkId, message)
  }
}

client.connect("demo-link", options, hooks, (result: TcpResult) => {
  console.log("connect result", result.code, result.message)
})

发送消息：

const packet: TcpLinkMessage = {
  linkId: "demo-link",
  payloadKind: "byte",
  bytes: [1, 2, 3, 4]
}

client.push(packet, (result) => {
  console.log("push result", result.code, result.message)
})

内置演示页

插件已在 uni_modules/laoqianjunzi-tcp/pages/index.uvue 提供完整演示页，覆盖以下操作：

• 启动与停止服务端
• 建立客户端连接与关闭连接
• 在 text / hex / byte 三种模式之间切换
• 单播、广播、断开会话、断开全部链路
• 查看服务端会话列表、客户端链路列表与运行日志

推荐联调步骤：

1. 打开演示页，使用“回环参数”按钮写入本机回环配置
2. 启动服务端监听 18897
3. 用客户端连接 127.0.0.1:18897
4. 先用 text 模式互发消息，再切换到 hex 和 byte 验证不同负载

常用演示输入：

• text：hello tcp
• hex：48656C6C6F20544350
• byte：72,101,108,108,111

API 速查

setTraceLevel(level)

设置插件调试日志级别。

TcpServerService

TcpClientService

TcpServerOptions

TcpPeerOptions

回调类型

TcpServerHooks

TcpClientHooks

数据结构

TcpResult

TcpSessionRecord

TcpLinkRecord

错误码

使用建议

• 对同一条通信链路，双方应约定统一的 payloadKind
• hex 模式下推荐传纯十六进制字符，不要依赖空格、短横线或大小写差异
• byte 模式下建议在业务层明确约束字节序、帧头和校验规则
• 若业务依赖长连接，建议在页面或服务生命周期结束时主动调用 stop()、stopWithResult()、disconnect() 或 disconnectAll() 释放资源
• 对性能敏感场景，建议显式设置缓冲区大小、超时与 keepAlive，不要完全依赖平台默认值

平台注意事项

• Android 需要网络与 Wi-Fi 状态权限
• iOS 需要本地网络访问说明，首次访问局域网能力时应关注系统权限提示
• Harmony 需要 INTERNET 权限
• Web 仅作演示与参数校验使用，所有真实 TCP 联调请在 App 平台完成

目录说明

如果你需要先看页面效果与调用顺序，建议从 uni_modules/laoqianjunzi-tcp/pages/index.uvue 开始，再回到业务页面按需封装自己的 TCP 服务层。