Node.js dgram模块实战：从UDP通信到广播组播全解析

如果你刚跑通console.log打印一个“1+2”，下一步大概率会碰到真正的 Node.js 网络编程。Node.js 里一提起写通信程序，大家第一反应都是net模块（TCP），但很多实时音视频、局域网设备发现、日志上报、游戏帧同步场景，选 UDP 反而更合理。这时候就要用到 dgram 模块，这是 Node.js 内置的 UDP 数据报通信实现，不需要额外装任何依赖，创建套接字、发包、收包、组播、广播都靠它。

这篇就是围绕 dgram 模块展开的完整实践笔记。我会先讲清楚 UDP 和 TCP 的区别，再拆解 dgram 的每个核心 API，最后给出一套能直接跑起来的回显服务、广播和组播示例，以及我踩过的几个坑。内容更适合已经熟悉 JavaScript 基础语法、想开始写网络程序的开发者，也适合那些用 Node.js 写工具脚本但一直没搞懂 UDP 为什么“不可靠”的人。

1. dgram 模块能干什么：先理解 UDP 的使用边界

1.1 UDP 和 TCP 的本质差异

很多人刚开始学网络编程，脑子里只有 TCP：建立连接、可靠传输、有序到达，觉得这才是“正常”的网络通信。但 UDP 走了完全相反的路子，它不建立连接、不保证送达、不保证顺序，甚至不保证数据报的完整性。这就是 dgram 模块的基础哲学：你调用一次send，系统就尽力把这个数据报发出去，能不能到、什么时候到、到了之后顺序对不对，UDP 协议本身一概不管。

那为什么还要用它？因为省掉了确认应答、连接维护、拥塞控制这一整套开销。TCP 每个包都要等 ACK，要维护滑动窗口，网络延迟高、吞吐抖动大的场景里，TCP 像是一个做事反复确认的同事；UDP 则像扔纸条，写了就扔，效率极高。dgram 模块给你提供的正是这种“最小可用”的通信能力，没有连接对象、没有流的概念，只有一个数据报接一个数据报。

1.2 dgram 适合哪些场景，不适合哪些场景

用 dgram 之前先判断业务能不能接受丢包和乱序。最适合的场景是实时性要求高、偶发丢包可容忍的领域，比如：

• 在线游戏的移动和状态同步，丢了上一帧就不补发了，直接用最新的。
• 音视频通话、直播推流，画面卡一下可以，等重传就完蛋了。
• 局域网内的设备发现，比如手机 App 搜智能音箱，广播一条“谁在”，能回应就行。
• 日志和监控指标上报，偶尔丢几条不影响整体统计。
• DNS 查询、NTP 时间同步这类“一问一答”式短消息，本质就是 UDP。
• 物联网传感器上报，数据量小、频率高，不需要为每一条建立清爽的可靠连接。

反过来，需要传输文件、需要保证每笔交易不丢、需要按顺序处理消息的场景，就不要硬用 dgram 了。文件上传下载、订单提交、聊天消息推送，这些老老实实走 TCP 或者在此基础上加 WebSocket。你可以在应用层给 UDP 加上重传和排序，但那是自己实现一个 TCP，复杂度和成本都高得多。选型判断就一句话：你想“快而糙”，还是“稳而慢”。

2. 核心 API 逐个拆：createSocket、bind、send、message

2.1 createSocket 和 bind：创建套接字并绑定端口

dgram 模块所有操作的起点是dgram.createSocket(type[, callback])，type二选一，'udp4'对应 IPv4，'udp6'对应 IPv6。绝大部分局域网和内网场景用'udp4'，如果要在 IPv6 环境中通信再使用'udp6'，两者创建的套接字不通用，地址格式也不一样。

const dgram = require('dgram'); const socket = dgram.createSocket('udp4');

创建出来的套接字一开始并没有监听任何端口。你要接收消息，就必须调用bind(port[, address][, callback])，指定服务端监听哪个端口。address可以省略，默认绑定到0.0.0.0，也就是本机所有网卡；如果只需要本机回环测试，也可以显式写'127.0.0.1'。

socket.bind(41234, () => { const address = socket.address(); console.log(`UDP 服务端已监听 ${address.address}:${address.port}`); });

这一点和 TCP 监听很像，但有个关键区别：TCP 的listen之后还有个“等连接进来”的过程，UDP 没有。bind一旦完成，只要数据报到达这个端口，就会触发message事件，不管对方之前有没有和你有过交互，这就是无连接特性在 API 层面的直接体现。

callback在绑定完成后触发，适合在这里打印监听地址。但不建议在这里做“开启业务逻辑”这样的事，因为消息随时可能进来，更稳妥的做法是提前注册好message监听，再调用bind。

2.2 send 才是主角：数据报怎么发出去

所有收包逻辑都围绕message事件展开，而发包逻辑紧紧围绕send方法。dgram 的send有两种常用形式，完整的签名是这样的：

socket.send(msg, offset, length, port, address[, callback]);

其中msg是Buffer、Uint8Array或字符串。offset和length表示从msg的第几个字节开始发、发多长。为什么要拆这么细？因为实际开发里经常是先拼一个大 Buffer，再截取其中一段作为消息内容，如果每次都要复制出一块新 Buffer，在高频发送场景下会白白增加内存拷贝。

新手最容易搞错的，是把port和address的顺序弄反。先写端口，再写 IP 地址，这个顺序是固定的，和 TCP 连接时的host:port写法刚好相反。如果写反了，程序不会直接报错，而是数据报发到了一个错误的目标，排查起来很费劲。

const message = Buffer.from('hello udp'); socket.send(message, 0, message.length, 41234, '127.0.0.1', (err) => { if (err) console.error('发送失败', err); else console.log('发送成功'); });

新版 Node.js 还支持更简洁的调用方式，把 offset 和 length 省掉，默认发送整个 Buffer：

socket.send(message, 41234, '127.0.0.1');

我自己写工具脚本时倾向用这种简短形式，但在要求精确控制包内容的项目里，我会用完整版本。原因很简单，UDP 数据报有最大长度限制，通常不建议超过 MTU 大小，手动指定offset和length可以方便你在协议层把消息切成多个分片发出去。

还有一个细节容易被忽略：客户端调用send之前，如果没有显式bind，系统会自动临时分配一个随机端口。这个随机端口对主动发送没问题，但如果服务端需要主动给客户端发送消息，客户端必须提前bind一个固定端口，否则服务端拿不到稳定的回调地址。

2.3 几个容易被忽略的辅助方法

send和message是核心，但有几个辅助方法在复杂场景里非常有用。

socket.address()返回当前绑定的地址信息对象，包含{ address, family, port }，在message事件回调里配合rinfo使用，可以区分“这是本机的地址”和“对方是谁发来的”。

socket.setBroadcast(flag)控制是否允许发送广播包。默认情况下发送到255.255.255.255会报错EACCES，必须设置socket.setBroadcast(true)才能把数据报发到广播地址。这里容易踩坑的是，flag参数是布尔值，而且一旦设置为true就作用于整个套接字，不区分目标地址，所以广播套接字最好不要同时承载需要保密的数据。

socket.setMulticastTTL(ttl)设置组播包的存活时间，决定这个包能在网络里传播多少跳。局域网内组播一般设置128足够，不需要改太大。

socket.setMulticastLoopback(flag)决定组播数据包是否回环回发给自己。同一台机器上即发即收的测试场景，需要把 loopback 设为true，否则接收端收不到自己进程发送的组播消息。

socket.setRecvBufferSize(size)和socket.setSendBufferSize(size)调整系统层面收发缓冲区大小。当消息量大、内核缓冲区溢出时，加大这个值能明显减少丢包，但注意它设置的是内核缓冲区，不是应用层队列，不要设到远超物理内存的水平。

socket.close()关闭套接字并释放端口。长期运行的服务端一般不需要频繁调用，但在脚本里跑完测试必须关闭，否则 Node.js 进程不会退出，终端一直挂着。

3. 从零写一个 UDP 回显服务：服务端 + 客户端完整代码

3.1 服务端：监听 message 事件，原样回发

写一个最简单的 UDP 回显服务，客户端发什么，服务端就原样返回什么。这和 TCP 的 echo 服务思路一致，但代码量少很多，因为没有连接管理和流处理。

const dgram = require('dgram'); const server = dgram.createSocket('udp4'); server.on('message', (msg, rinfo) => { console.log(`收到来自 ${rinfo.address}:${rinfo.port} 数据: ${msg.toString()}`); server.send(msg, rinfo.port, rinfo.address, (err) => { if (err) { console.error('回发失败', err); } }); }); server.on('listening', () => { const address = server.address(); console.log(`UDP 服务端已启动 ${address.address}:${address.port}`); }); server.on('error', (err) => { console.error('服务端发生错误', err); server.close(); }); server.bind(41234, '0.0.0.0');

每个message回调都会收到两个参数：第一个msg是 Buffer，也就是对方发来的原始数据；第二个rinfo是发送方信息，包括address、port、family和size字段。回发时必须用rinfo.port和rinfo.address，因为 UDP 没有连接对象，你不能像 TCP 那样直接往某个已建立的 socket 上写数据，必须每次携带目标地址。

这里注意msg的类型是 Buffer，不是字符串。如果业务数据是文本，记得调用msg.toString()；如果是二进制协议数据，比如结构体、序列化后的对象，就不要做字符串转换，直接用 Buffer 操作。

3.2 客户端：send + message 组合拳

客户端这边，既要发送数据，也要监听服务端回包，所以它也必须是一个 dgram 套接字，哪怕不主动bind固定端口。

const dgram = require('dgram'); const client = dgram.createSocket('udp4'); const message = Buffer.from('你好，UDP!'); client.send(message, 41234, '127.0.0.1', (err) => { if (err) { console.error('发送失败', err); client.close(); } else { console.log('消息已发送，等待响应...'); } }); client.on('message', (msg, rinfo) => { console.log(`收到服务端响应: ${msg.toString()} (来自 ${rinfo.address}:${rinfo.port})`); client.close(); }); client.on('error', (err) => { console.error('客户端错误', err); client.close(); });

这个逻辑里有个细节：send的回调和message事件是分开的。如果发送失败，在send回调里能拿到err并做处理；如果发送成功，后续服务端回包会通过message事件回到客户端。也就是说，一次 UDP 请求-应答流程由“一个发送动作 + 一个事件监听”组合完成，这和 TCP 的“连接建立后流式读写”体验差异很大，刚开始容易摸不着头脑。

还有一个实际的坑：如果服务端没启动，或者地址写错了，客户端send并不会立刻报错。UDP 是无连接的，数据报发出去了，系统就认为发送成功，至于有没有人接收，协议层不关心。所以调试 UDP 程序，第一件事永远是先确认服务端已经bind并监听端口，再用ss -unlp | grep 41234或者netstat查看端口状态。

3.3 跑通了之后，再做一步“伪连接”封装

基本回显跑通后，你会发现每次发送都要传port和address，写多了很啰嗦。dgram 也想到了这一点，提供了一个connect(port, address[, callback])方法，但它不是 TCP 那种真正的连接，只是给套接字设置一个“默认发送地址”。之后再用socket.send(msg)发送时，就不需要再指定端口和 IP 了。

const dgram = require('dgram'); const client = dgram.createSocket('udp4'); client.connect(41234, '127.0.0.1', () => { client.send('连上了，这就是伪连接', (err) => { if (err) { console.error('发送失败', err); } }); });

connect之后，远程地址被记录在套接字内部，send会默认发到那里。但这个“连接”只是本地状态，不通知服务端，也没有握手，服务端依然是一视同仁地处理所有到达端口的数据报。这个特性适合客户端长期固定和一个服务端通信的场景，可以减少重复参数，还能通过监听error事件更快发现目标不可达。

不过要记住，伪连接不会改变 UDP 的不可靠本质，别指望连接之后就有了拥塞控制和重传机制。

3.4 中途踩过的字节序和 Buffer 坑

说一个我最初写 dgram 程序时翻车的经历。当时想把一个整数统计值随消息发出去，直接用了Buffer.from([255, 0])，结果接收端解出来的数字完全不对。原因很简单，整数在二进制协议里有高字节和低字节的顺序问题，也就是大端序和小端序的差别。TCP 也一样有这个问题，但 UDP 的开发更底层，很多人会直接在 Buffer 上操作数字，这个坑就更容易踩中。

我的习惯是，在应用层协议里统一使用大端序，也就是网络字节序。Node.js 的 Buffer 提供了现成方法：

const buf = Buffer.alloc(4); buf.writeUInt32BE(1024, 0);

对方收到后，用buf.readUInt32BE(0)还原，就能拿到正确的 1024。消息中如果有多个字段，建议先用Buffer.alloc分配合适的空间，再用writeUInt16BE、writeUInt32BE或writeFloatBE逐个写入，最后通过socket.send(buf, ...)发出去。整个过程不要依赖隐式的字符串拼接，字节序出错的 bug 很难排查，现场日志看到的是一堆莫名其妙的数字。

4. 广播与组播：dgram 实现一对多通信

4.1 局域网广播：setBroadcast 之后发到 255.255.255.255

UDP 最强大的特性之一就是一对多通信。最简单的实现是广播，把数据报发送到当前子网的所有设备。IPv4 的广播地址是255.255.255.255，发送到这个地址的包，路由器不会转发，但同一局域网内所有主机的 UDP 端口如果监听在目标端口上，都能收到。

在 Node.js 里发送广播，必须设置setBroadcast(true)，否则发送255.255.255.255会直接报错。

const dgram = require('dgram'); const sender = dgram.createSocket('udp4'); sender.bind(() => { sender.setBroadcast(true); const msg = Buffer.from('局域网广播：有人吗？'); sender.send(msg, 5000, '255.255.255.255', (err) => { if (err) { console.error('广播发送失败', err); } else { console.log('广播已发送'); } setTimeout(() => sender.close(), 2000); }); });

接收端和平时的 UDP 服务端没有区别，绑定对应端口，监听message事件即可。需要注意，广播能到达的范围由子网掩码决定。如果两台机器不在同一个广播域，比如中间隔了路由器，广播就无法跨网段传播，这是广播方式的天然限制。

我自己做局域网内服务发现时，早期就是用广播实现的。手机 App 发一条广播，同网段所有安装了对应服务的电脑都会响应，然后把 IP 和端口汇报上来。这个方案实现简单，但在较大的网络里，广播会产生大量无差别流量，影响整个子网。所以在规模稍微大一点的场景，我建议用组播代替广播。

4.2 组播：addMembership + setMulticastTTL 的组合

组播（multicast）更像“订阅者模式”。发送方把数据发到一个特定的组播地址，比如239.0.0.100，只有加入了该组的接收方才能收到。相比广播，组播不会打扰无关设备，而且可以跨越支持组播的路由器传播。

接收方要加入组播组，核心是addMembership方法：

const dgram = require('dgram'); const receiver = dgram.createSocket('udp4'); const MULTICAST_ADDR = '239.0.0.100'; const PORT = 6000; receiver.on('message', (msg) => { console.log(`收到组播消息: ${msg.toString()}`); }); receiver.bind(PORT, '0.0.0.0', () => { receiver.addMembership(MULTICAST_ADDR); console.log(`已加入组播组 ${MULTICAST_ADDR}:${PORT}`); });

addMembership告诉底层协议栈，这个套接字要接收发送到该组播地址的数据报。如果不调用这个方法，即使端口对上，也收不到组播包。

发送方不需要加入组播组，只需要把数据发到组播地址：

const dgram = require('dgram'); const sender = dgram.createSocket('udp4'); const MULTICAST_ADDR = '239.0.0.100'; const PORT = 6000; sender.bind(() => { sender.setMulticastTTL(128); sender.setMulticastLoopback(true); const msg = Buffer.from('这是一条组播消息'); sender.send(msg, 0, msg.length, PORT, MULTICAST_ADDR, (err) => { if (err) { console.error('组播发送失败', err); } else { console.log('组播消息已发送'); } setTimeout(() => sender.close(), 2000); }); });

这里setMulticastLoopback(true)很关键。如果接收方和发送方在同一台机器上调试，只有打开 loopback，本机进程才能收到自己发出去的组播包。如果 loopback 是关闭的，在远程机器上可能一切正常，本地却怎么都收不到，非常容易误判为代码问题。

组播地址的选取有讲究。224.0.0.0到239.255.255.255都是 IPv4 组播地址段，但其中一部分被协议保留，不能用在自己的业务里。一般我会用239.0.0.0/8，这是本地管理范围，可以随便分。不要在224.0.0.x里选，那些大多保留给路由协议。

4.3 多网卡环境怎么指定出口

笔记本、服务器经常有多个网络接口，一个 Wi-Fi、一个网线、一个虚拟机的虚拟网卡。这种情况下，dgram 的默认行为是把数据从“系统选择的默认网卡”发出去，但这不是我们总想要的。如果当前默认网卡是虚拟机网卡，广播和组播消息就发不到真实局域网。

addMembership支持第二个参数，用来指定加入组播时使用的本机网卡 IP：

receiver.addMembership(MULTICAST_ADDR, '192.168.1.100');

发送端也可以把绑定地址指定到具体网卡：

sender.bind(0, '192.168.1.100', () => { sender.setMulticastInterface('192.168.1.100'); });

setMulticastInterface用于设置组播数据发送时使用的网络接口，这个方法设一次之后会覆盖默认行为。真机调试前，先用ip addr（Linux）或者ipconfig（Windows）看下网卡 IP，确认你要发的数据该走哪个网卡，再把它传给 dgram，可以少踩很多环境坑。

5. 高负载下的 UDP：丢包、乱序、粘包问题排查记录

5.1 数据报边界：为什么 UDP 不用处理粘包

接触过 TCP 的人都知道粘包问题：TCP 是字节流，消息之间没有天然边界，应用层要设计分隔符或固定长度去拆包。UDP 则完全相反，它是数据报协议，每次send调用对应一个完整数据报，接收端的message事件也是一次回调对应一个数据报。也就是说，发送方调用两次send，接收方就会收到两个message事件，不会出现两个消息粘在一起。

但边界清晰不代表没有新问题。如果发送速度太快、接收缓冲区太小，数据报会直接在内核层被丢弃。这种丢弃不是“消息残缺”——单个 UDP 数据报要么完整到达、要么整个丢弃，不会出现半截消息。所以 UDP 编程里你不需要拆包，但需要面对丢包和乱序。这是把双刃剑，省去了粘包处理的复杂度，却把可靠性的责任转移到了应用层。

5.2 应用层协议怎么设计：加序列号和长度字段

既然 UDP 不保证可靠，生产环境里应用层协议就要自己兜底。我的做法是在每个数据报的最前面加一个固定头部，至少包含两个字段：

• 消息序号seq：用UInt32BE表示，连续发送的消息序号递增，接收方通过序号发现丢包和乱序。
• 消息长度length：用UInt16BE表示，标示后面业务数据的总长度。

发送端拼包：

const payload = Buffer.from('业务数据'); const header = Buffer.alloc(6); header.writeUInt32BE(seq, 0); header.writeUInt16BE(payload.length, 4); const packet = Buffer.concat([header, payload]); socket.send(packet, PORT, ADDR);

接收端拆包：

socket.on('message', (msg) => { if (msg.length < 6) { console.warn('数据报长度异常，丢弃'); return; } const seq = msg.readUInt32BE(0); const len = msg.readUInt16BE(4); const payload = msg.subarray(6, 6 + len); console.log(`收到消息 #${seq}，长度 ${len}`); });

有了序号，接收方可以做乱序重排；如果检测到某个序号缺失，可以决定是立即请求重传，还是直接跳过等待最新数据。业务上还要做去重，因为应用层重传后同一个序号可能到达两次。这套机制写起来不复杂，却是 UDP 生产化的基础。纯 UDP 裸奔在真实业务里基本撑不过一天。

5.3 端口被占用、跨网段收不到、收发不匹配

把 dgram 用起来的路上，有三类问题比较典型，我分开说。

第一类是端口被占用。错误码是EADDRINUSE，和 TCP 一样。Linux 下用lsof -i :41234查占用进程，Windows 用netstat -ano | findstr 41234。Node 服务重启时如果上一个进程没有正常退出，端口会处于 TIME_WAIT 或暂未释放状态，稍等几秒再启动，或者直接在代码里监听error事件做重试策略。

第二类是跨网段收不到。局域网内两台机器能互相 ping 通，但 UDP 消息就是到不了。这是广播和组播场景最容易遇到的现象，原因是路由器默认不转发广播包。跨网段通信要么部署组播路由器支持 IGMP，要么干脆改用 TCP 或上层代理。我建议不要纠结，直接改单播，简单可靠，很多 IoT 场景的头疼问题其实都是选型不当造成的。

第三类是收发不匹配。客户端和服务端明明都在跑，但收不到响应，先用本机回环测试127.0.0.1，如果回环能通、局域网不同，重点查防火墙。很多系统的防火墙会拦截入站 UDP 包，需要在系统防火墙里放行对应的 UDP 端口。还有一个隐蔽情况是服务器绑定的是127.0.0.1，只能本机访问，外部自然收不到响应。bind时用0.0.0.0才可以监听所有网卡。

5.4 常见问题速查表

5.5 小技巧：用 tcpdump 和 Wireshark 观察 UDP 流量

调试 UDP 程序，光靠 console.log 不够，因为很多问题出在“数据报到底有没有被发出 / 有没有真正到达”这一层。我的习惯是，先在本机跑 tcpdump 看包：

sudo tcpdump -i any udp port 41234 -X

如果看到包发出去了，但接收端没有日志，问题在接收端的套接字配置；如果包根本没出现，问题在发送端的地址、广播开关或网卡绑定。这个思路比盲改代码高效太多。

Wireshark 更适合看数据中心负载和协议细节。打开捕获后，过滤条件填udp.port == 41234，就能看到每一条数据报的时间戳、源地址、目标地址和载荷内容。我在分析乱序和数据报分片问题时，都是靠 Wireshark 的图形化排序功能，一眼就能看出哪个序号早到了、哪个包被切成多个 IP 分片了。

有了这些排查手段，再用 dgram 做真实项目，会稳妥很多。UDP 的坑大多不是 Node.js 特有的，而是网络协议本身的特性，理解了底层原理，再回头看 dgram 的 API 设计，就会觉得一切都顺理成章了。