更新记录

1.0.0（2026-06-17）

插件1.0.0版本

平台兼容性

uni-app(4.66)

uni-app x(4.66)

wen-udp

UDP 网络服务插件，支持 UDP 服务端、UDP 客户端功能。常用于物联网、智能家居、iot、局域网设备发现、设备交互控制、消息通知等场景，支持苹果、安卓。

平台兼容性

uni-app (4.66)

uni-app x (4.66)

导入 uni_modules 规范插件需使用 HBuilderX 4.66+。

关于插件

本插件为 uni-app / uni-app x 提供原生 UDP 通信能力。UDP 通常用于局域网内设备发现、消息广播通知等场景。

• 支持在 APP 端建立 UDP 服务端，接收外部设备（通常是局域网设备）发送过来的消息。支持同时建立多个 UDP 服务端。支持单播、组播、广播。
• 支持在 APP 端建立 UDP 客户端，连接到外部的 UDP 服务端进行通信。支持同时建立多个 UDP 客户端。支持单播、组播、广播。
• 额外提供 getLocalIp() 获取本机 IPv4 地址。

如何使用

基础概念

• UDP 单播（Unicast）：一对一通信，数据从单个发送方传输到单个接收方。数据包通过目标 IP 地址和端口直接送达指定主机。
• UDP 组播（Multicast）：一对多通信，发送方将数据发送到一个组播组地址（范围：224.0.0.0 ~ 239.255.255.255），加入该组的所有主机都能接收数据。
• UDP 广播（Broadcast）：一对所有通信，数据发送到本地网络的所有主机（目标 IP 为广播地址，如 255.255.255.255 或子网广播地址 192.168.1.255）。

引入

import { createUdpServer, createUdpClient, getLocalIp } from '@/uni_modules/wen-udp';

UDP 服务端基本使用

使用 createUdpServer 建立 UDP 服务端。

// 初始化【单播】UDP 服务端
let unicastUdpServer = createUdpServer({
  port: 20101
})

// 注册接收回调
unicastUdpServer.on('message', (msg) => {
  console.log('【单播-服务端】接收到消息:', msg.remoteAddress, msg.data)
})
unicastUdpServer.on('error', (err) => {
  console.error('错误消息:', err)
})
unicastUdpServer.start()

// 初始化【广播】UDP 服务端
let broadcastUdpServer = createUdpServer({
  port: 20101,
  isBroadcast: true
})
broadcastUdpServer.on('message', (msg) => {
  console.log('【广播-服务端】接收到消息:', msg.remoteAddress, msg.data)
})
broadcastUdpServer.on('error', (err) => {
  console.error('错误消息:', err)
})
broadcastUdpServer.start()

// 初始化【组播】UDP 服务端
let multicastUdpServer = createUdpServer({
  port: 20101,
  isBroadcast: true,
  isMulticast: true,
  multicastAddress: '239.192.1.10'   // 组播地址，必填
})
multicastUdpServer.on('message', (msg) => {
  console.log('【组播-服务端】接收到消息:', msg.remoteAddress, msg.data)
})
multicastUdpServer.on('error', (err) => {
  console.error('错误消息:', err)
})
multicastUdpServer.start()

发送（单播、广播、组播）消息，支持 text 文本 与 hex 十六进制字符串 两种格式：

/////////// 不同 UDP 链接发送消息示例 ///////////

// 单播服务端发送文本
unicastUdpServer.send('hello, world', '192.168.50.130', 30101)

// 广播服务端发送 hex
broadcastUdpServer.sendHex(
  '68656C6C6F2C2062726F616463617374',   // hello, broadcast
  '192.168.50.255',                     // 子网广播；"255.255.255.255" 为全网广播，iOS 限制较严
  30102
)

// 组播服务端发送文本
multicastUdpServer.send('hello, multicast', '239.192.1.10', 30103)

/////////// 支持多种数据格式示例 ///////////

// 发送文本
unicastUdpServer.send('hello, world', '192.168.50.130', 30101)

// 发送 hex 字符串
unicastUdpServer.sendHex('68656c6c6f2c313233', '192.168.50.130', 30101)   // hello,123

关闭链接：

unicastUdpServer.stop()

UDP 客户端基本使用

使用 createUdpClient 建立 UDP 客户端。

// 初始化【单播】UDP 客户端
let unicastUdpClient = createUdpClient({
  localPort: 0,          // 0 表示随机端口；同端口收发场景可指定具体端口
  isBroadcast: false
})
unicastUdpClient.on('message', (msg) => {
  console.log('【单播-客户端】接收到消息:', msg.remoteAddress, msg.data)
})
unicastUdpClient.on('error', (err) => {
  console.error('错误消息:', err)
})
unicastUdpClient.start()
console.log('本地端口:', unicastUdpClient.getLocalPort())

// 初始化【广播】UDP 客户端
let broadcastUdpClient = createUdpClient({
  localPort: 0,
  isBroadcast: true      // 发送广播时必须 true
})
broadcastUdpClient.on('message', (msg) => {
  console.log('【广播-客户端】接收到消息:', msg.remoteAddress, msg.data)
})
broadcastUdpClient.on('error', (err) => {
  console.error('错误消息:', err)
})
broadcastUdpClient.start()

// 初始化【组播】UDP 客户端
let multicastUdpClient = createUdpClient({
  localPort: 0,
  isBroadcast: true
})
multicastUdpClient.on('message', (msg) => {
  console.log('【组播-客户端】接收到消息:', msg.remoteAddress, msg.data)
})
multicastUdpClient.on('error', (err) => {
  console.error('错误消息:', err)
})
multicastUdpClient.start()

发送消息（客户端 send / sendHex 需指定目标 IP 与端口）：

// 发送文本
unicastUdpClient.send('hello, world', '192.168.50.130', 30101)

// 发送 hex
unicastUdpClient.sendHex('68656c6c6f2c313233', '192.168.50.130', 30101)

// 发送广播
broadcastUdpClient.send('LITECAYDODISCOVERY', '255.255.255.255', 10008)

// 发送组播
multicastUdpClient.send('hello, multicast', '239.192.1.10', 30101)

关闭客户端链接：

unicastUdpClient.stop()

接收消息

收到的消息对象包含以下字段：

获取本机 IP

const ip = getLocalIp()   // 优先 WiFi / 以太网 IPv4，失败返回 ""
if (ip.length > 0) {
  console.log('本机 IP:', ip)
}

典型场景示例

局域网设备发现（广播 + 固定服务端端口回推）：

// 1. 服务端监听固定端口，等设备单播回推
const server = createUdpServer({ port: 49736, isBroadcast: true })
server.start()

// 2. 客户端广播发现报文（先 start 再 send）
const client = createUdpClient({ localPort: 0, isBroadcast: true })
client.start()
client.send('LITECAYDODISCOVERY:49736', '255.255.255.255', 10008)

// 3. 在 server 上通过 on() 或 pollMessage() 接收设备回推

组播接收（SSDP 等）：

const ms = createUdpServer({
  port: 1900,
  isBroadcast: true,
  isMulticast: true,
  multicastAddress: '239.255.255.250'
})
ms.start()

权限要求

安卓 Android 权限

插件已在 AndroidManifest.xml 中声明，一般无需手动添加：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" />

苹果 iOS 权限（需要苹果开发者平台申请权限）

插件已在 Info.plist 与 UTS.entitlements 中配置。若主工程需补充，可参考：

<key>NSLocalNetworkUsageDescription</key>
<string>需要扫描本地网络设备以提供服务</string>
<key>NSMulticastServiceUsageDescription</key>
<string>需要加入多播组以实现群组通信</string>
<key>NSAllowsLocalNetworking</key>
<true/>
<key>UIBackgroundModes</key>
<array>
    <string>network</string>
</array>

附：API 速查

模块方法

服务端配置 createUdpServer(options)

客户端配置 createUdpClient(options)

实例方法（Server / Client 通用）

注意事项

1. start() 之后再调用 getLocalPort()，-1 表示绑定失败。
2. 广播 / 组播须设置 isBroadcast: true；广播目标可用 "255.255.255.255" 或子网广播 "192.168.1.255"。
3. Android 广播失败时会自动对当前 /24 子网做单播扫射兜底；Socket 自动绑定 WiFi 网卡，避免走蜂窝网络。
4. 同一端口不可重复绑定；页面卸载时记得 stop() 并清除 poll 定时器。

隐私、权限声明

1. 本插件需要申请的系统权限列表：

请查看上方「权限要求」章节。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件不采集任何数据。

3. 本插件是否包含广告：

无。

完整可运行示例见项目 pages/index/index.uvue（UDP 调试助手）。