UDP/数据报套接字

[稳定: 2 - 稳定]

node:dgram 模块提供 UDP 数据报套接字的实现。

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`server error:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`server listening ${address.address}:${address.port}`)
})

server.bind(41234)
// 输出: server listening 0.0.0.0:41234

const dgram = require('node:dgram')
const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`server error:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`server listening ${address.address}:${address.port}`)
})

server.bind(41234)
// 输出: server listening 0.0.0.0:41234

类: `dgram.Socket`

新增于: v0.1.99

继承自: <EventEmitter>

封装数据报功能。

dgram.Socket 的新实例使用 dgram.createSocket() 创建。不要使用 new 关键字创建 dgram.Socket 实例。

事件: `'close'`

新增于: v0.1.99

'close' 事件在使用 close() 关闭套接字后发出。一旦触发，此套接字将不再发出新的 'message' 事件。

事件: `'connect'`

新增于: v12.0.0

'connect' 事件在套接字由于成功调用 connect() 而与远程地址关联后发出。

事件: `'error'`

新增于: v0.1.99

exception <Error>

每当发生任何错误时，都会发出 'error' 事件。事件处理程序函数传递一个 Error 对象。

事件：`'listening'`

新增于：v0.1.99

当 dgram.Socket 可寻址并可以接收数据时，将发出 'listening' 事件。这可以通过 socket.bind() 明确指定，也可以在第一次使用 socket.send() 发送数据时隐式发生。在 dgram.Socket 监听之前，底层系统资源不存在，诸如 socket.address() 和 socket.setTTL() 之类的调用将失败。

事件：`'message'`

[历史]

版本	变更
v18.4.0	`family` 属性现在返回字符串而不是数字。
v18.0.0	`family` 属性现在返回数字而不是字符串。
v0.1.99	新增于：v0.1.99

当套接字上有新的数据报可用时，将发出 'message' 事件。事件处理函数传递两个参数：msg 和 rinfo。

msg <Buffer> 消息。
rinfo <Object> 远程地址信息。
- address <string> 发送方地址。
- family <string> 地址族 ('IPv4' 或 'IPv6')。
- port <number> 发送方端口。
- size <number> 消息大小。

如果传入数据包的源地址是 IPv6 链路本地地址，则接口名称将添加到 address 中。例如，在 en0 接口上接收到的数据包的地址字段可能设置为 'fe80::2618:1234:ab11:3b9c%en0'，其中 '%en0' 是作为区域 ID 后缀的接口名称。

`socket.addMembership(multicastAddress[, multicastInterface])`

新增于：v0.6.9

multicastAddress <string>
multicastInterface <string>

使用 IP_ADD_MEMBERSHIP 套接字选项，告知内核加入给定 multicastAddress 和 multicastInterface 的多播组。如果未指定 multicastInterface 参数，操作系统将选择一个接口并向其添加成员资格。要向每个可用接口添加成员资格，请多次调用 addMembership，每个接口一次。

在未绑定的套接字上调用此方法时，它将隐式绑定到随机端口，并在所有接口上监听。

在多个 cluster 工作进程之间共享 UDP 套接字时，socket.addMembership() 函数必须只调用一次，否则会发生 EADDRINUSE 错误：

ESMCJS

import cluster from 'node:cluster'
import dgram from 'node:dgram'

if (cluster.isPrimary) {
  cluster.fork() // 工作正常。
  cluster.fork() // 发生 EADDRINUSE 错误。
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

const cluster = require('node:cluster')
const dgram = require('node:dgram')

if (cluster.isPrimary) {
  cluster.fork() // 工作正常。
  cluster.fork() // 发生 EADDRINUSE 错误。
} else {
  const s = dgram.createSocket('udp4')
  s.bind(1234, () => {
    s.addMembership('224.0.0.114')
  })
}

`socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

新增于: v13.1.0, v12.16.0

sourceAddress <string>
groupAddress <string>
multicastInterface <string>

告知内核使用 IP_ADD_SOURCE_MEMBERSHIP 套接字选项，在给定的 sourceAddress 和 groupAddress 加入源特定组播通道，使用 multicastInterface。如果未指定 multicastInterface 参数，操作系统将选择一个接口并添加成员资格。要向每个可用接口添加成员资格，请多次调用 socket.addSourceSpecificMembership()，每个接口一次。

在未绑定套接字上调用此方法时，此方法将隐式绑定到随机端口，侦听所有接口。

`socket.address()`

新增于：v0.1.99

返回值：<Object>

返回一个包含套接字地址信息的对象。对于 UDP 套接字，此对象将包含 address、family 和 port 属性。

如果在未绑定的套接字上调用此方法，则会抛出 EBADF 错误。

`socket.bind([port][, address][, callback])`

[历史]

版本	变更
v0.9.1	该方法更改为异步执行模型。旧代码需要更改为向方法调用传递回调函数。
v0.1.99	新增于：v0.1.99

port <int>
address <String>
callback <Function> 无参数。绑定完成后调用。

对于 UDP 套接字，这将导致 dgram.Socket 监听指定 port 和可选 address 上的数据报消息。如果未指定 port 或为 0，则操作系统将尝试绑定到随机端口。如果未指定 address，则操作系统将尝试监听所有地址。绑定完成后，将发出 'listening' 事件，并调用可选的 callback 函数。

同时指定 'listening' 事件监听器和向 socket.bind() 方法传递 callback 并不会造成危害，但也没有什么用。

绑定的数据报套接字使 Node.js 进程保持运行以接收数据报消息。

如果绑定失败，则会生成 'error' 事件。在极少数情况下（例如尝试使用已关闭的套接字进行绑定），可能会抛出 Error 错误。

监听 41234 端口的 UDP 服务器示例：

ESMCJS

import dgram from 'node:dgram'

const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`server error:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`server listening ${address.address}:${address.port}`)
})

server.bind(41234)
// 输出：server listening 0.0.0.0:41234

const dgram = require('node:dgram')
const server = dgram.createSocket('udp4')

server.on('error', err => {
  console.error(`server error:\n${err.stack}`)
  server.close()
})

server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`)
})

server.on('listening', () => {
  const address = server.address()
  console.log(`server listening ${address.address}:${address.port}`)
})

server.bind(41234)
// 输出：server listening 0.0.0.0:41234

`socket.bind(options[, callback])`

新增于: v0.11.14

options <Object> 必需。支持以下属性：
- port <integer>
- address <string>
- exclusive <boolean>
- fd <integer>
callback <Function>

对于 UDP 套接字，导致 dgram.Socket 监听传递为 options 对象属性的命名 port 和可选 address 上的数据报消息。如果未指定 port 或为 0，则操作系统将尝试绑定到随机端口。如果未指定 address，则操作系统将尝试监听所有地址。绑定完成后，将发出 'listening' 事件，并调用可选的 callback 函数。

options 对象可能包含 fd 属性。当设置 fd 大于 0 时，它将围绕具有给定文件描述符的现有套接字进行包装。在这种情况下，将忽略 port 和 address 的属性。

同时指定 'listening' 事件监听器并将 callback 传递给 socket.bind() 方法不会造成危害，但也没有什么用处。

options 对象可能包含一个附加的 exclusive 属性，该属性在将 dgram.Socket 对象与 cluster 模块一起使用时使用。当 exclusive 设置为 false（默认值）时，集群工作进程将使用相同的底层套接字句柄，从而允许共享连接处理职责。但是，当 exclusive 为 true 时，句柄不会共享，并且尝试共享端口会导致错误。使用 reusePort 选项设置为 true 创建 dgram.Socket 会导致在调用 socket.bind() 时 exclusive 始终为 true。

绑定的数据报套接字使 Node.js 进程保持运行以接收数据报消息。

如果绑定失败，则会生成 'error' 事件。在极少数情况下（例如，尝试使用已关闭的套接字绑定），可能会抛出 Error。

下面显示了一个在专用端口上监听的套接字示例。

socket.bind({
  address: 'localhost',
  port: 8000,
  exclusive: true,
})

`socket.close([callback])`

新增于: v0.1.99

callback <函数> 当套接字关闭时调用。

关闭底层套接字并停止监听其上的数据。如果提供了回调函数，则将其添加为 'close' 事件的监听器。

`socket[Symbol.asyncDispose]()`

新增于: v20.5.0, v18.18.0

[稳定性: 1 - 实验性]

稳定性: 1 稳定性: 1 - 实验性

调用 socket.close() 并返回一个 promise，该 promise 在套接字关闭时 fulfilled。

`socket.connect(port[, address][, callback])`

新增于: v12.0.0

port <整数>
address <字符串>
callback <函数> 连接完成或发生错误时调用。

将 dgram.Socket 与远程地址和端口关联。通过此句柄发送的每条消息都会自动发送到该目标。此外，套接字将只接收来自该远程对等方的消息。尝试在一个已经连接的套接字上调用 connect() 将导致 ERR_SOCKET_DGRAM_IS_CONNECTED 异常。如果未提供 address，则默认使用 '127.0.0.1'（对于 udp4 套接字）或 '::1'（对于 udp6 套接字）。连接完成后，将发出 'connect' 事件，并调用可选的 callback 函数。如果失败，则调用 callback，或者如果失败，则发出 'error' 事件。

`socket.disconnect()`

新增于：v12.0.0

一个同步函数，用于断开已连接的 dgram.Socket 与其远程地址的关联。尝试对未绑定或已断开的套接字调用 disconnect() 将导致 ERR_SOCKET_DGRAM_NOT_CONNECTED 异常。

`socket.dropMembership(multicastAddress[, multicastInterface])`

新增于：v0.6.9

multicastAddress <string>
multicastInterface <string>

指示内核使用 IP_DROP_MEMBERSHIP 套接字选项离开 multicastAddress 处的多播组。当套接字关闭或进程终止时，内核会自动调用此方法，因此大多数应用程序无需调用此方法。

如果未指定 multicastInterface，操作系统将尝试在所有有效接口上取消组成员身份。

`socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

新增于: v13.1.0, v12.16.0

sourceAddress <string>
groupAddress <string>
multicastInterface <string>

指示内核使用 IP_DROP_SOURCE_MEMBERSHIP 套接字选项离开给定 sourceAddress 和 groupAddress 的源特定组播通道。当套接字关闭或进程终止时，内核会自动调用此方法，因此大多数应用程序都不需要调用此方法。

如果未指定 multicastInterface，操作系统将尝试取消所有有效接口上的成员资格。

`socket.getRecvBufferSize()`

新增于: v8.7.0

返回值: <number> SO_RCVBUF 套接字接收缓冲区大小（以字节为单位）。

如果在未绑定的套接字上调用此方法，则会抛出 ERR_SOCKET_BUFFER_SIZE 错误。

`socket.getSendBufferSize()`

新增于：v8.7.0

返回值： <number> 以字节为单位的 SO_SNDBUF 套接字发送缓冲区大小。

如果在未绑定的套接字上调用此方法，则会抛出 ERR_SOCKET_BUFFER_SIZE 错误。

`socket.getSendQueueSize()`

新增于：v18.8.0, v16.19.0

返回值： <number> 已排队等待发送的字节数。

`socket.getSendQueueCount()`

新增于：v18.8.0, v16.19.0

返回值： <number> 当前正在队列中等待处理的发送请求数。

`socket.ref()`

新增于：v0.9.1

返回值： <dgram.Socket>

默认情况下，绑定套接字会导致 Node.js 进程在套接字打开时阻塞退出。可以使用 socket.unref() 方法将套接字从保持 Node.js 进程活动的引用计数中排除。socket.ref() 方法将套接字添加回引用计数并恢复默认行为。

多次调用 socket.ref() 不会产生额外的影响。

socket.ref() 方法返回对套接字的引用，以便可以链接调用。

`socket.remoteAddress()`

新增于：v12.0.0

返回值：<Object>

返回一个包含远程端点的address、family和port的对象。如果套接字未连接，此方法将抛出ERR_SOCKET_DGRAM_NOT_CONNECTED异常。

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

[历史]

版本	变更
v17.0.0	`address`参数现在只接受`string`、`null`或`undefined`。
v14.5.0, v12.19.0	`msg`参数现在可以是任何`TypedArray`或`DataView`。
v12.0.0	添加了对已连接套接字发送数据支持。
v8.0.0	`msg`参数现在可以是`Uint8Array`。
v8.0.0	`address`参数现在始终是可选的。
v6.0.0	成功时，`callback`现在将使用`null`而不是`0`作为`error`参数被调用。
v5.7.0	`msg`参数现在可以是数组。此外，`offset`和`length`参数现在是可选的。
v0.1.99	新增于：v0.1.99

msg <Buffer> | <TypedArray> | <DataView> | <string> | <Array> 要发送的消息。
offset <integer> 缓冲区中消息开始的偏移量。
length <integer> 消息中的字节数。
port <integer> 目标端口。
address <string> 目标主机名或 IP 地址。
callback <Function> 消息发送完毕后调用。

在套接字上广播数据报。对于无连接套接字，必须指定目标port和address。另一方面，已连接的套接字将使用其关联的远程端点，因此不能设置port和address参数。

msg参数包含要发送的消息。根据其类型，不同的行为可能适用。如果msg是Buffer、任何TypedArray或DataView，则offset和length分别指定消息在Buffer中开始的偏移量和消息中的字节数。如果msg是String，则它将使用'utf8'编码自动转换为Buffer。对于包含多字节字符的消息，offset和length将根据字节长度而不是字符位置计算。如果msg是数组，则必须不指定offset和length。

address参数是字符串。如果address的值是主机名，则将使用 DNS 解析主机的地址。如果未提供address或为 nullish，则将默认使用'127.0.0.1'（对于udp4套接字）或'::1'（对于udp6套接字）。

如果套接字之前没有通过调用bind绑定，则套接字将被分配一个随机端口号并绑定到“所有接口”地址（对于udp4套接字为'0.0.0.0'，对于udp6套接字为'::0'）。

可以指定一个可选的callback函数，作为报告 DNS 错误或确定何时可以安全重用buf对象的一种方式。DNS 查找会将发送时间至少延迟 Node.js 事件循环的一个周期。

确定数据报已发送的唯一方法是使用callback。如果发生错误并且给出了callback，则错误将作为第一个参数传递给callback。如果没有给出callback，则错误将作为socket对象上的'error'事件发出。

Offset 和 length 是可选的，但是如果使用了其中一个，则必须同时设置两者。它们仅在第一个参数是 Buffer、TypedArray 或 DataView 时受支持。

如果在未绑定的套接字上调用此方法，则会抛出ERR_SOCKET_BAD_PORT。

向localhost上的端口发送 UDP 数据包的示例；

ESMCJS

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.send(message, 41234, 'localhost', err => {
  client.close()
})

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.send(message, 41234, 'localhost', err => {
  client.close()
})

发送由多个缓冲区组成的 UDP 数据包到127.0.0.1端口的示例；

ESMCJS

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const buf1 = Buffer.from('Some ')
const buf2 = Buffer.from('bytes')
const client = dgram.createSocket('udp4')
client.send([buf1, buf2], 41234, err => {
  client.close()
})

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const buf1 = Buffer.from('Some ')
const buf2 = Buffer.from('bytes')
const client = dgram.createSocket('udp4')
client.send([buf1, buf2], 41234, err => {
  client.close()
})

发送多个缓冲区可能会更快或更慢，具体取决于应用程序和操作系统。运行基准测试以逐个案例确定最佳策略。但是，一般来说，发送多个缓冲区更快。

使用连接到localhost端口的套接字发送 UDP 数据包的示例：

ESMCJS

import dgram from 'node:dgram'
import { Buffer } from 'node:buffer'

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.connect(41234, 'localhost', err => {
  client.send(message, err => {
    client.close()
  })
})

const dgram = require('node:dgram')
const { Buffer } = require('node:buffer')

const message = Buffer.from('Some bytes')
const client = dgram.createSocket('udp4')
client.connect(41234, 'localhost', err => {
  client.send(message, err => {
    client.close()
  })
})

关于 UDP 数据报大小的说明

IPv4/v6 数据报的最大大小取决于 MTU（最大传输单元）和 Payload Length（有效负载长度）字段的大小。

Payload Length 字段为 16 位宽，这意味着普通有效负载不能超过 64K 字节，包括互联网报头和数据（65,507 字节 = 65,535 − 8 字节 UDP 报头 − 20 字节 IP 报头）；这通常适用于环回接口，但对于大多数主机和网络来说，如此长的数据报消息是不切实际的。
MTU 是给定链路层技术能够支持的数据报消息的最大大小。对于任何链路，IPv4 规定最小 MTU 为 68 字节，而 IPv4 的推荐 MTU 为 576（通常推荐作为拨号类型应用程序的 MTU），无论它们是完整到达还是分段到达。对于 IPv6，最小 MTU 为 1280 字节。但是，强制的最小分片重组缓冲区大小为 1500 字节。68 字节的值非常小，因为大多数当前的链路层技术，如以太网，最小 MTU 为 1500。

无法预先知道数据包可能经过的每条链路的 MTU。发送大于接收方 MTU 的数据报将无法工作，因为数据包将被静默丢弃，不会通知源数据未到达预期的接收方。

`socket.setBroadcast(flag)`

新增于：v0.6.9

flag <布尔值>

设置或清除 SO_BROADCAST 套接字选项。设置为 true 时，UDP 数据包可以发送到本地接口的广播地址。

如果在未绑定的套接字上调用此方法，则会抛出 EBADF 错误。

`socket.setMulticastInterface(multicastInterface)`

新增于：v8.6.0

multicastInterface <字符串>

本节中所有关于作用域的引用都指的是 IPv6 区域索引，其由RFC 4007 定义。字符串形式的带有作用域索引的 IP 写作 'IP%scope'，其中 scope 是接口名称或接口编号。

将套接字的默认传出多播接口设置为选定的接口或返回系统接口选择。multicastInterface 必须是套接字族中有效 IP 的字符串表示形式。

对于 IPv4 套接字，这应该是为所需物理接口配置的 IP。发送到套接字上的多播的所有数据包都将通过此调用的最近一次成功使用确定的接口发送。

对于 IPv6 套接字，multicastInterface 应包含一个作用域以指示接口，如下面的示例所示。在 IPv6 中，单个 send 调用也可以在地址中使用显式作用域，因此只有发送到多播地址且未指定显式作用域的数据包才会受到此调用的最近一次成功使用影响。

如果在未绑定的套接字上调用此方法，则会抛出 EBADF 错误。

示例：IPv6 出站多播接口

在大多数系统上，范围格式使用接口名称：

const socket = dgram.createSocket('udp6')

socket.bind(1234, () => {
  socket.setMulticastInterface('::%eth1')
})

在 Windows 系统上，范围格式使用接口编号：

const socket = dgram.createSocket('udp6')

socket.bind(1234, () => {
  socket.setMulticastInterface('::%2')
})

示例：IPv4 出站多播接口

所有系统都使用所需物理接口上主机的 IP 地址：

const socket = dgram.createSocket('udp4')

socket.bind(1234, () => {
  socket.setMulticastInterface('10.0.0.2')
})

调用结果

对尚未准备好发送或不再打开的套接字进行调用可能会抛出 Not running Error 错误。

如果无法将 multicastInterface 解析为 IP 地址，则会抛出 EINVAL System Error 错误。

在 IPv4 上，如果 multicastInterface 是有效的地址，但不匹配任何接口，或者地址与族不匹配，则会抛出 System Error 错误，例如 EADDRNOTAVAIL 或 EPROTONOSUP。

在 IPv6 上，指定或省略范围的大多数错误都会导致套接字继续使用（或返回到）系统的默认接口选择。

套接字的地址族 ANY 地址（IPv4 '0.0.0.0' 或 IPv6 '::'）可用于将套接字的默认出站接口的控制权返回给系统，用于未来的多播数据包。

`socket.setMulticastLoopback(flag)`

Added in: v0.3.8

flag <布尔值>

设置或清除 IP_MULTICAST_LOOP 套接字选项。设置为 true 时，多播数据包也会在本地接口上接收。

此方法如果在未绑定的套接字上调用，则会抛出 EBADF 错误。

`socket.setMulticastTTL(ttl)`

Added in: v0.3.8

ttl <整数>

设置 IP_MULTICAST_TTL 套接字选项。虽然 TTL 通常代表“生存时间”，但在这种情况下，它指定数据包允许通过的 IP 跳数，特别是对于多播流量。每个转发数据包的路由器或网关都会递减 TTL。如果路由器将 TTL 递减到 0，则不会转发它。

ttl 参数可以是 0 到 255 之间的任何值。大多数系统上的默认值为 1。

此方法如果在未绑定的套接字上调用，则会抛出 EBADF 错误。

`socket.setRecvBufferSize(size)`

新增于：v8.7.0

size <整数>

设置 SO_RCVBUF 套接字选项。设置最大套接字接收缓冲区（以字节为单位）。

如果在未绑定的套接字上调用此方法，则会抛出 ERR_SOCKET_BUFFER_SIZE 错误。

`socket.setSendBufferSize(size)`

新增于：v8.7.0

size <整数>

设置 SO_SNDBUF 套接字选项。设置最大套接字发送缓冲区（以字节为单位）。

如果在未绑定的套接字上调用此方法，则会抛出 ERR_SOCKET_BUFFER_SIZE 错误。

`socket.setTTL(ttl)`

新增于：v0.1.101

ttl <整数>

设置 IP_TTL 套接字选项。虽然 TTL 通常代表“生存时间”，但在这种情况下，它指定数据包允许通过的 IP 跳数。每个转发数据包的路由器或网关都会递减 TTL。如果路由器将 TTL 递减到 0，则不会转发该数据包。更改 TTL 值通常用于网络探测或多播时。

ttl 参数可以是 1 到 255 之间的任何值。大多数系统上的默认值为 64。

如果在未绑定的套接字上调用此方法，则会抛出 EBADF 错误。

`socket.unref()`

新增于: v0.9.1

返回值: <dgram.Socket>

默认情况下，绑定套接字会阻止 Node.js 进程退出，只要套接字处于打开状态。socket.unref() 方法可以用来将套接字排除在保持 Node.js 进程活跃的引用计数之外，允许进程即使套接字仍在监听也能退出。

多次调用 socket.unref() 不会产生额外的影响。

socket.unref() 方法返回套接字的引用，以便可以链接调用。

`node:dgram` 模块函数

`dgram.createSocket(options[, callback])`

[历史]

版本	变更
v23.1.0	支持 `reusePort` 选项。
v15.8.0	添加了 AbortSignal 支持。
v11.4.0	支持 `ipv6Only` 选项。
v8.7.0	现在支持 `recvBufferSize` 和 `sendBufferSize` 选项。
v8.6.0	支持 `lookup` 选项。
v0.11.13	新增于: v0.11.13

options <Object> 可用的选项包括：
- type <string> 套接字族。必须是 'udp4' 或 'udp6' 之一。必需。
- reuseAddr <boolean> 当为 true 时，socket.bind() 将重用地址，即使另一个进程已在其上绑定了套接字，但也只有一个套接字可以接收数据。默认值： false。
- reusePort <boolean> 当为 true 时，socket.bind() 将重用端口，即使另一个进程已在其上绑定了套接字。传入的数据报将分配给监听套接字。此选项仅在某些平台上可用，例如 Linux 3.9+、DragonFlyBSD 3.6+、FreeBSD 12.0+、Solaris 11.4 和 AIX 7.2.5+。在不支持的平台上，绑定套接字时此选项会引发错误。默认值： false。
- ipv6Only <boolean> 将 ipv6Only 设置为 true 将禁用双栈支持，即，绑定到地址 :: 不会使 0.0.0.0 被绑定。默认值： false。
- recvBufferSize <number> 设置 SO_RCVBUF 套接字值。
- sendBufferSize <number> 设置 SO_SNDBUF 套接字值。
- lookup <Function> 自定义查找函数。默认值： dns.lookup()。
- signal <AbortSignal> 可用于关闭套接字的 AbortSignal。
- receiveBlockList <net.BlockList> receiveBlockList 可用于丢弃到特定 IP 地址、IP 范围或 IP 子网的入站数据报。如果服务器位于反向代理、NAT 等之后，则此方法不起作用，因为针对阻止列表检查的地址是代理的地址，或 NAT 指定的地址。
- sendBlockList <net.BlockList> sendBlockList 可用于禁用到特定 IP 地址、IP 范围或 IP 子网的出站访问。
callback <Function> 附加为 'message' 事件的监听器。可选。
返回值: <dgram.Socket>

创建一个 dgram.Socket 对象。创建套接字后，调用 socket.bind() 将指示套接字开始监听数据报消息。当未将 address 和 port 传递给 socket.bind() 时，该方法会将套接字绑定到随机端口上的“所有接口”地址（对 udp4 和 udp6 套接字都执行正确的操作）。可以使用 socket.address().address 和 socket.address().port 检索绑定的地址和端口。

如果启用了 signal 选项，则在相应的 AbortController 上调用 .abort() 与在套接字上调用 .close() 类似：

const controller = new AbortController()
const { signal } = controller
const server = dgram.createSocket({ type: 'udp4', signal })
server.on('message', (msg, rinfo) => {
  console.log(`server got: ${msg} from ${rinfo.address}:${rinfo.port}`)
})
// 稍后，当您想关闭服务器时。
controller.abort()

`dgram.createSocket(type[, callback])`

新增于: v0.1.99

type <string> 'udp4' 或 'udp6' 之一。
callback <Function> 作为监听器附加到 'message' 事件。
返回值: <dgram.Socket>

创建一个指定 type 的 dgram.Socket 对象。

一旦套接字创建完成，调用 socket.bind() 将指示套接字开始监听数据报消息。当未将 address 和 port 传递给 socket.bind() 时，该方法将套接字绑定到随机端口上的“所有接口”地址（对 udp4 和 udp6 套接字都适用）。绑定的地址和端口可以使用 socket.address().address 和 socket.address().port 来检索。

UDP/数据报套接字 ​

类: dgram.Socket ​

事件: 'close' ​

事件: 'connect' ​

事件: 'error' ​

事件：'listening' ​

事件：'message' ​

socket.addMembership(multicastAddress[, multicastInterface]) ​

socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface]) ​

socket.address() ​

socket.bind([port][, address][, callback]) ​

socket.bind(options[, callback]) ​

socket.close([callback]) ​

socket[Symbol.asyncDispose]() ​

socket.connect(port[, address][, callback]) ​

socket.disconnect() ​

socket.dropMembership(multicastAddress[, multicastInterface]) ​

socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface]) ​

socket.getRecvBufferSize() ​

socket.getSendBufferSize() ​

socket.getSendQueueSize() ​

socket.getSendQueueCount() ​

socket.ref() ​

socket.remoteAddress() ​

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

关于 UDP 数据报大小的说明 ​

socket.setBroadcast(flag) ​

socket.setMulticastInterface(multicastInterface) ​

示例：IPv6 出站多播接口 ​

示例：IPv4 出站多播接口 ​

调用结果 ​

socket.setMulticastLoopback(flag) ​

socket.setMulticastTTL(ttl) ​

socket.setRecvBufferSize(size) ​

socket.setSendBufferSize(size) ​

socket.setTTL(ttl) ​

socket.unref() ​

node:dgram 模块函数 ​

dgram.createSocket(options[, callback]) ​

dgram.createSocket(type[, callback]) ​

UDP/数据报套接字

类: `dgram.Socket`

事件: `'close'`

事件: `'connect'`

事件: `'error'`

事件：`'listening'`

事件：`'message'`

`socket.addMembership(multicastAddress[, multicastInterface])`

`socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

`socket.address()`

`socket.bind([port][, address][, callback])`

`socket.bind(options[, callback])`

`socket.close([callback])`

`socket[Symbol.asyncDispose]()`

`socket.connect(port[, address][, callback])`

`socket.disconnect()`

`socket.dropMembership(multicastAddress[, multicastInterface])`

`socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])`

`socket.getRecvBufferSize()`

`socket.getSendBufferSize()`

`socket.getSendQueueSize()`

`socket.getSendQueueCount()`

`socket.ref()`

`socket.remoteAddress()`

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

关于 UDP 数据报大小的说明

`socket.setBroadcast(flag)`

`socket.setMulticastInterface(multicastInterface)`

示例：IPv6 出站多播接口

示例：IPv4 出站多播接口

调用结果

`socket.setMulticastLoopback(flag)`

`socket.setMulticastTTL(ttl)`

`socket.setRecvBufferSize(size)`

`socket.setSendBufferSize(size)`

`socket.setTTL(ttl)`

`socket.unref()`

`node:dgram` 模块函数

`dgram.createSocket(options[, callback])`

`dgram.createSocket(type[, callback])`