Node.js v21.7.2 文档

IPC 支持#

node:net 模块支持 Windows 上的命名管道和其它操作系统上的 Unix 域套接字的 IPC。

识别 IPC 连接的路径#

net.connect()、net.createConnection()、server.listen() 和 socket.connect() 接受一个 path 参数来识别 IPC 端点。

在 Unix 上，本地域也称为 Unix 域。路径是一个文件系统路径名。它会被截断为操作系统相关的长度 sizeof(sockaddr_un.sun_path) - 1。典型的值在 Linux 上为 107 字节，在 macOS 上为 103 字节。如果 Node.js API 抽象创建了 Unix 域套接字，它也会解除链接 Unix 域套接字。例如，net.createServer() 可能会创建一个 Unix 域套接字，而 server.close() 会解除链接它。但是，如果用户在这些抽象之外创建了 Unix 域套接字，则用户需要将其删除。当 Node.js API 创建了一个 Unix 域套接字，但程序随后崩溃时，也是如此。简而言之，Unix 域套接字将在文件系统中可见，并将持续存在，直到解除链接。在 Linux 上，您可以通过在路径的开头添加 \0 来使用 Unix 抽象套接字，例如 \0abstract。Unix 抽象套接字的路径在文件系统中不可见，并且当所有对套接字的打开引用都被关闭时，它将自动消失。

在 Windows 上，本地域使用命名管道实现。路径必须引用 \\?\pipe\ 或 \\.\pipe\ 中的条目。允许使用任何字符，但后者可能会对管道名称进行一些处理，例如解析 .. 序列。尽管它可能看起来像这样，但管道命名空间是扁平的。管道不会持久化。当对它们的最后一个引用被关闭时，它们将被删除。与 Unix 域套接字不同，Windows 会在拥有进程退出时关闭并删除管道。

JavaScript 字符串转义要求路径使用额外的反斜杠转义来指定，例如

net.createServer().listen(
  path.join('\\\\?\\pipe', process.cwd(), 'myctl')); copy

类: net.BlockList#

BlockList 对象可与某些网络 API 一起使用，以指定规则，用于禁用对特定 IP 地址、IP 范围或 IP 子网的入站或出站访问。

blockList.addAddress(address[, type])#

• address <string> | <net.SocketAddress> IPv4 或 IPv6 地址。
• type <string> 可以是 'ipv4' 或 'ipv6'。默认值： 'ipv4'。

添加一条规则来阻止给定的 IP 地址。

blockList.addRange(start, end[, type])#

• start <string> | <net.SocketAddress> 范围内的起始 IPv4 或 IPv6 地址。
• end <string> | <net.SocketAddress> 范围内的结束 IPv4 或 IPv6 地址。
• type <string> 可以是 'ipv4' 或 'ipv6'。默认值： 'ipv4'。

添加一条规则来阻止从 start（包含）到 end（包含）的一系列 IP 地址。

blockList.addSubnet(net, prefix[, type])#

• net <string> | <net.SocketAddress> 网络 IPv4 或 IPv6 地址。
• prefix <number> CIDR 前缀位的数量。对于 IPv4，这必须是一个介于 0 和 32 之间的数字。对于 IPv6，这必须介于 0 和 128 之间。
• type <string> 可以是 'ipv4' 或 'ipv6'。默认值： 'ipv4'。

添加一条规则来阻止作为子网掩码指定的一系列 IP 地址。

blockList.check(address[, type])#

• address <string> | <net.SocketAddress> 要检查的 IP 地址
• type <string> 可以是 'ipv4' 或 'ipv6'。默认值： 'ipv4'。
• 返回值： <boolean>

如果给定的 IP 地址与添加到 BlockList 的任何规则匹配，则返回 true。

const blockList = new net.BlockList();
blockList.addAddress('123.123.123.123');
blockList.addRange('10.0.0.1', '10.0.0.10');
blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6');

console.log(blockList.check('123.123.123.123'));  // Prints: true
console.log(blockList.check('10.0.0.3'));  // Prints: true
console.log(blockList.check('222.111.111.222'));  // Prints: false

// IPv6 notation for IPv4 addresses works:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true copy

blockList.rules#

• 类型： <string[]>

添加到阻止列表的规则列表。

类： net.SocketAddress#

new net.SocketAddress([options])#

• options <Object>
  • address <string> 网络地址，可以是 IPv4 或 IPv6 字符串。默认值：如果 family 为 'ipv4'，则为 '127.0.0.1'；如果 family 为 'ipv6'，则为 '::'。
  • family <string> 'ipv4' 或 'ipv6' 之一。默认值：'ipv4'。
  • flowlabel <number> 仅当 family 为 'ipv6' 时使用的 IPv6 流标签。
  • port <number> IP 端口。

socketaddress.address#

• 类型 <string>

socketaddress.family#

• 类型 <string> 'ipv4' 或 'ipv6' 之一。

socketaddress.flowlabel#

• 类型 <number>

socketaddress.port#

• 类型 <number>

类：net.Server#

• 扩展：<EventEmitter>

此类用于创建 TCP 或 IPC 服务器。

new net.Server([options][, connectionListener])#

• options <Object> 查看 net.createServer([options][, connectionListener]).
• connectionListener <Function> 自动设置为 'connection' 事件的监听器。
• 返回值: <net.Server>

net.Server 是一个 EventEmitter，具有以下事件

事件: 'close'#

当服务器关闭时发出。如果存在连接，则此事件在所有连接结束之前不会发出。

事件: 'connection'#

• <net.Socket> 连接对象

当建立新连接时发出。socket 是 net.Socket 的实例。

事件: 'error'#

• <Error>

当发生错误时发出。与 net.Socket 不同，除非手动调用 server.close()，否则 'close' 事件不会在此事件之后直接发出。请参阅 server.listen() 讨论中的示例。

事件: 'listening'#

在调用 server.listen() 后，当服务器绑定后发出。

事件: 'drop'#

当连接数达到 server.maxConnections 的阈值时，服务器将丢弃新的连接并发出 'drop' 事件。如果它是 TCP 服务器，则参数如下，否则参数为 undefined。

• data <Object> 传递给事件监听器的参数。
  • localAddress <string> 本地地址。
  • localPort <number> 本地端口。
  • localFamily <string> 本地族。
  • remoteAddress <string> 远程地址。
  • remotePort <number> 远程端口。
  • remoteFamily <string> 远程 IP 族。'IPv4' 或 'IPv6'。

server.address()#

• 返回值：<Object> | <string> | <null>

返回绑定的 address、地址 family 名称和服务器的 port，这些信息由操作系统报告，前提是服务器正在监听 IP 套接字（用于查找在获取操作系统分配的地址时分配了哪个端口）：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }。

对于监听管道或 Unix 域套接字的服务器，名称将作为字符串返回。

const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // Handle errors here.
  throw err;
});

// Grab an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
}); copy

在 'listening' 事件发出之前或调用 server.close() 之后，server.address() 返回 null。

server.close([callback])#

• callback <Function> 当服务器关闭时调用。
• 返回值: <net.Server>

停止服务器接受新连接，并保持现有连接。此函数是异步的，服务器在所有连接结束并服务器发出 'close' 事件后最终关闭。可选的 callback 将在 'close' 事件发生后调用。与该事件不同的是，如果服务器在关闭时未打开，它将仅使用 Error 作为其唯一参数进行调用。

server[Symbol.asyncDispose]()#

调用 server.close() 并返回一个 promise，该 promise 在服务器关闭时完成。

server.getConnections(callback)#

• callback <Function>
• 返回值: <net.Server>

异步获取服务器上的并发连接数。在套接字被发送到 fork 时有效。

回调应接受两个参数 err 和 count。

server.listen()#

启动服务器以监听连接。net.Server 可以是 TCP 服务器或 IPC 服务器，具体取决于它监听的内容。

可能的签名

• server.listen(handle[, backlog][, callback])
• server.listen(options[, callback])
• server.listen(path[, backlog][, callback]) 用于 IPC 服务器
• server.listen([port[, host[, backlog]]][, callback]) 用于 TCP 服务器

此函数是异步的。当服务器开始监听时，将发出 'listening' 事件。最后一个参数 callback 将被添加为 'listening' 事件的监听器。

所有 listen() 方法都可以接受一个 backlog 参数来指定挂起连接队列的最大长度。实际长度将由操作系统通过 sysctl 设置决定，例如 Linux 上的 tcp_max_syn_backlog 和 somaxconn。此参数的默认值为 511（而不是 512）。

所有 net.Socket 都设置为 SO_REUSEADDR（有关详细信息，请参阅 socket(7)）。

如果且仅当第一次 server.listen() 调用期间发生错误或已调用 server.close() 时，才能再次调用 server.listen() 方法。否则，将抛出 ERR_SERVER_ALREADY_LISTEN 错误。

监听时最常见的错误之一是 EADDRINUSE。当另一个服务器已经在请求的 port/path/handle 上监听时，就会发生这种情况。处理此问题的一种方法是在一段时间后重试

server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
}); copy

server.listen(handle[, backlog][, callback])#

• handle <Object>
• backlog <number> server.listen() 函数的通用参数
• callback <Function>
• 返回值: <net.Server>

启动一个服务器，监听已绑定到端口、Unix 域套接字或 Windows 命名管道的给定 handle 上的连接。

handle 对象可以是服务器、套接字（任何具有底层 _handle 成员的东西），或者具有 fd 成员的对象，该成员是有效的文件描述符。

在 Windows 上不支持监听文件描述符。

server.listen(options[, callback])#

• options <Object> 必需。支持以下属性
  • port <number>
  • host <string>
  • path <string> 如果指定了 port，则会被忽略。请参阅 为 IPC 连接识别路径。
  • backlog <number> server.listen() 函数的常用参数。
  • exclusive <boolean> 默认值： false
  • readableAll <boolean> 对于 IPC 服务器，使管道对所有用户可读。默认值： false。
  • writableAll <boolean> 对于 IPC 服务器，使管道对所有用户可写。默认值： false。
  • ipv6Only <boolean> 对于 TCP 服务器，将 ipv6Only 设置为 true 将禁用双栈支持，即绑定到主机 :: 不会使 0.0.0.0 被绑定。默认值： false。
  • signal <AbortSignal> 可以用来关闭监听服务器的 AbortSignal。
• callback <Function> 函数。
• 返回值: <net.Server>

如果指定了 port，则其行为与 server.listen([port[, host[, backlog]]][, callback]) 相同。否则，如果指定了 path，则其行为与 server.listen(path[, backlog][, callback]) 相同。如果两者都没有指定，则会抛出错误。

如果 exclusive 为 false（默认值），则集群工作进程将使用相同的底层句柄，允许共享连接处理职责。当 exclusive 为 true 时，句柄不会共享，并且尝试端口共享会导致错误。下面显示了一个监听专用端口的示例。

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true,
}); copy

当 exclusive 为 true 且底层句柄是共享的时，多个 worker 可能会查询具有不同 backlog 的句柄。在这种情况下，将使用传递给主进程的第一个 backlog。

以 root 身份启动 IPC 服务器可能会导致服务器路径对无特权用户不可访问。使用 readableAll 和 writableAll 将使服务器对所有用户可访问。

如果启用了 signal 选项，则在相应的 AbortController 上调用 .abort() 等同于在服务器上调用 .close()

const controller = new AbortController();
server.listen({
  host: 'localhost',
  port: 80,
  signal: controller.signal,
});
// Later, when you want to close the server.
controller.abort(); copy

server.listen(path[, backlog][, callback])#

• path <string> 服务器应该监听的路径。请参阅 标识 IPC 连接的路径。
• backlog <number> server.listen() 函数的常用参数。
• callback <Function>.
• 返回值: <net.Server>

启动一个 IPC 服务器，监听给定 path 上的连接。

server.listen([port[, host[, backlog]]][, callback])#

• port <number>
• host <string>
• backlog <number> server.listen() 函数的常用参数。
• callback <Function>.
• 返回值: <net.Server>

启动一个 TCP 服务器，监听给定 port 和 host 上的连接。

如果省略了 port 或 port 为 0，操作系统将分配一个任意的未使用端口，该端口可以在 'listening' 事件发出后使用 server.address().port 获取。

如果省略了 host，服务器将在 IPv6 可用时接受 未指定 IPv6 地址 (::) 上的连接，否则接受 未指定 IPv4 地址 (0.0.0.0) 上的连接。

在大多数操作系统中，监听 未指定 IPv6 地址 (::) 可能会导致 net.Server 也监听 未指定 IPv4 地址 (0.0.0.0)。

server.listening#

• <boolean> 指示服务器是否正在监听连接。

server.maxConnections#

• <integer>

当服务器的连接数变高时，将此属性设置为拒绝连接。

一旦套接字已发送到子进程，不建议使用此选项 child_process.fork()。

server.ref()#

• 返回值: <net.Server>

与 unref() 相反，在先前 unref 的服务器上调用 ref() 不会 让程序在它是唯一剩余的服务器时退出（默认行为）。如果服务器被 ref，再次调用 ref() 将不会有任何效果。

server.unref()#

• 返回值: <net.Server>

在服务器上调用 unref() 将允许程序在事件系统中这是唯一活动的服务器时退出。如果服务器已经被 unref，再次调用 unref() 将不会有任何效果。

类：net.Socket#

• 扩展：<stream.Duplex>

此类是 TCP 套接字或流式 IPC 端点（在 Windows 上使用命名管道，在其他情况下使用 Unix 域套接字）的抽象。它也是一个 EventEmitter。

net.Socket 可以由用户创建并直接用于与服务器交互。例如，它由 net.createConnection() 返回，因此用户可以使用它与服务器通信。

它也可以由 Node.js 创建并传递给用户，当收到连接时。例如，它被传递给 net.Server 上发出的 'connection' 事件的监听器，因此用户可以使用它与客户端交互。

new net.Socket([options])#

• options <Object> 可用选项是
  • fd <number> 如果指定，则使用给定文件描述符包装现有套接字，否则将创建一个新套接字。
  • allowHalfOpen <boolean> 如果设置为 false，则当可读端结束时，套接字将自动结束可写端。有关详细信息，请参阅 net.createServer() 和 'end' 事件。默认值： false。
  • readable <boolean> 当传递 fd 时，允许在套接字上进行读取，否则忽略。默认值： false。
  • writable <boolean> 当传递 fd 时，允许在套接字上进行写入，否则忽略。默认值： false。
  • signal <AbortSignal> 可用于销毁套接字的 Abort 信号。
• 返回值： <net.Socket>

创建一个新的套接字对象。

新创建的套接字可以是 TCP 套接字或流式 IPC 端点，具体取决于它 connect() 的内容。

事件： 'close'#

• hadError <boolean> 如果套接字存在传输错误，则为 true。

套接字完全关闭后发出一次。参数 hadError 是一个布尔值，表示套接字是否因传输错误而关闭。

事件： 'connect'#

套接字连接成功建立时发出。请参阅 net.createConnection()。

事件： 'connectionAttempt'#

• ip <string> 套接字尝试连接到的 IP。
• port <number> 套接字尝试连接到的端口。
• family <number> IP 的族。可以是 6 表示 IPv6 或 4 表示 IPv4。

当新的连接尝试开始时发出。如果在 socket.connect(options) 中启用了族自动选择算法，则可能会多次发出此事件。

事件：'connectionAttemptFailed'#

• ip <string> 套接字尝试连接到的 IP。
• port <number> 套接字尝试连接到的端口。
• family <number> IP 的族。它可以是 IPv6 的 6 或 IPv4 的 4。* error <Error> 与失败相关的错误。

当连接尝试失败时发出。如果在 socket.connect(options) 中启用了族自动选择算法，则可能会多次发出此事件。

事件：'connectionAttemptTimeout'#

• ip <string> 套接字尝试连接到的 IP。
• port <number> 套接字尝试连接到的端口。
• family <number> IP 的族。可以是 6 表示 IPv6 或 4 表示 IPv4。

当连接尝试超时时发出。仅当在 socket.connect(options) 中启用了族自动选择算法时才会发出此事件（并且可能会多次发出）。

事件：'data'#

• <Buffer> | <string>

当收到数据时发出。参数 data 将是 Buffer 或 String。数据的编码由 socket.setEncoding() 设置。

如果 Socket 发出 'data' 事件时没有监听器，则数据将丢失。

事件：'drain'#

当写入缓冲区变为空时发出。可用于限制上传。

另请参阅：socket.write() 的返回值。

事件: 'end'#

当套接字的另一端发出传输结束信号时发出，从而结束套接字的可读端。

默认情况下（allowHalfOpen 为 false），套接字将在写入其待处理的写入队列后发送一个传输结束数据包并销毁其文件描述符。但是，如果将 allowHalfOpen 设置为 true，套接字将不会自动 end() 其可写端，允许用户写入任意数量的数据。用户必须显式调用 end() 来关闭连接（即发送一个 FIN 数据包）。

事件: 'error'#

• <Error>

发生错误时发出。'close' 事件将在该事件之后直接调用。

事件: 'lookup'#

在解析主机名但连接之前发出。不适用于 Unix 套接字。

• err <Error> | <null> 错误对象。参见 dns.lookup()。
• address <string> IP 地址。
• family <number> | <null> 地址类型。参见 dns.lookup()。
• host <string> 主机名。

事件: 'ready'#

当套接字准备好使用时发出。

在 'connect' 之后立即触发。

事件: 'timeout'#

如果套接字因无活动而超时，则发出。这只是为了通知套接字处于空闲状态。用户必须手动关闭连接。

另请参见: socket.setTimeout()。

socket.address()#

• 返回值: <Object>

返回绑定到套接字的 address、套接字的地址 family 名称和 port，这些信息由操作系统报告：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.autoSelectFamilyAttemptedAddresses#

• <string[]>

此属性仅在 socket.connect(options) 中启用地址族自动选择算法时存在，它是一个包含已尝试地址的数组。

每个地址都是 $IP:$PORT 格式的字符串。如果连接成功，则最后一个地址是套接字当前连接到的地址。

socket.bufferSize#

• <integer>

此属性显示为写入缓冲的字符数。缓冲区可能包含编码后长度未知的字符串。因此，此数字只是缓冲区中字节数的近似值。

net.Socket 具有 socket.write() 始终有效的属性。这有助于用户快速上手。计算机无法始终跟上写入套接字的数据量。网络连接可能太慢。Node.js 会在内部将写入套接字的数据排队，并在可能时将其发送到网络。

这种内部缓冲的后果是内存可能会增长。遇到大型或不断增长的 bufferSize 的用户应尝试使用 socket.pause() 和 socket.resume() 来“限制”程序中的数据流。

socket.bytesRead#

• <integer>

接收到的字节数。

socket.bytesWritten#

• <integer>

发送的字节数。

socket.connect()#

在给定的套接字上启动连接。

可能的签名

• socket.connect(options[, connectListener])
• socket.connect(path[, connectListener]) 用于 IPC 连接。
• socket.connect(port[, host][, connectListener]) 用于 TCP 连接。
• 返回值: <net.Socket> 套接字本身。

此函数是异步的。当连接建立时，将发出 'connect' 事件。如果连接存在问题，则不会发出 'connect' 事件，而是会发出 'error' 事件，并将错误传递给 'error' 监听器。如果提供了最后一个参数 connectListener，它将被添加为 'connect' 事件的监听器 一次。

此函数仅应在 'close' 事件发出后用于重新连接套接字，否则可能会导致未定义的行为。

socket.connect(options[, connectListener])#

• options <Object>
• connectListener <Function> 是 socket.connect() 方法的通用参数。它将作为 'connect' 事件的监听器添加一次。
• 返回值: <net.Socket> 套接字本身。

在给定的套接字上启动连接。通常不需要此方法，套接字应该使用 net.createConnection() 创建和打开。仅在实现自定义套接字时使用此方法。

对于 TCP 连接，可用的 options 是

• port <number> 必需。套接字应该连接到的端口。
• host <string> 套接字应该连接到的主机。默认值： 'localhost'。
• localAddress <string> 套接字应该连接的本地地址。
• localPort <number> 套接字应该连接的本地端口。
• family <number>: IP 堆栈的版本。必须是 4、6 或 0。值 0 表示允许 IPv4 和 IPv6 地址。默认值： 0。
• hints <number> 可选的 dns.lookup() 提示。
• lookup <Function> 自定义查找函数。默认值： dns.lookup()。
• noDelay <boolean> 如果设置为 true，则在套接字建立后立即禁用 Nagle 算法的使用。默认值： false。
• keepAlive <boolean> 如果设置为 true，则在连接建立后立即在套接字上启用保持活动功能，类似于 socket.setKeepAlive([enable][, initialDelay]) 中的操作。默认值： false。
• keepAliveInitialDelay <number> 如果设置为正数，则在空闲套接字上发送第一个保持活动探测之前设置初始延迟。默认值： 0。
• autoSelectFamily <boolean>: 如果设置为 true，则启用一个家庭自动检测算法，该算法松散地实现了 RFC 8305 的第 5 节。传递给查找的 all 选项设置为 true，并且套接字尝试按顺序连接到所有获得的 IPv6 和 IPv4 地址，直到建立连接。首先尝试返回的第一个 AAAA 地址，然后尝试返回的第一个 A 地址，然后尝试返回的第二个 AAAA 地址，依此类推。每次连接尝试（除了最后一次）都会在超时并尝试下一个地址之前，等待由 autoSelectFamilyAttemptTimeout 选项指定的时间量。如果 family 选项不是 0 或 localAddress 已设置，则忽略。如果至少有一个连接成功，则不会发出连接错误。如果所有连接尝试都失败，则会发出一个包含所有失败尝试的单个 AggregateError。默认值： net.getDefaultAutoSelectFamily()
• autoSelectFamilyAttemptTimeout <number>: 使用 autoSelectFamily 选项时，在尝试下一个地址之前，等待连接尝试完成的毫秒数。如果设置为小于 10 的正整数，则将使用值 10。默认值： net.getDefaultAutoSelectFamilyAttemptTimeout()

对于 IPC 连接，可用的 options 是

• path <string> 必需。客户端应连接到的路径。请参阅 识别 IPC 连接的路径。如果提供，则上面的 TCP 特定选项将被忽略。

对于这两种类型，可用的 options 包括

• onread <Object> 如果指定，则传入数据将存储在一个 buffer 中，并在数据到达套接字时传递给提供的 callback。这将导致流功能不提供任何数据。套接字将像往常一样发出事件，例如 'error'、'end' 和 'close'。pause() 和 resume() 等方法也将按预期工作。
  • buffer <Buffer> | <Uint8Array> | <Function> 用于存储传入数据的可重用内存块或返回此类内存块的函数。
  • callback <Function> 此函数在收到每个传入数据块时调用。它传递两个参数：写入 buffer 的字节数和对 buffer 的引用。从该函数返回 false 将隐式 pause() 套接字。此函数将在全局上下文中执行。

以下是使用 onread 选项的客户端示例

const net = require('node:net');
net.connect({
  port: 80,
  onread: {
    // Reuses a 4KiB Buffer for every read from the socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // Received data is available in `buf` from 0 to `nread`.
      console.log(buf.toString('utf8', 0, nread));
    },
  },
}); copy

socket.connect(path[, connectListener])#

• path <string> 客户端应连接到的路径。请参阅 识别 IPC 连接的路径。
• connectListener <Function> 是 socket.connect() 方法的通用参数。它将作为 'connect' 事件的监听器添加一次。
• 返回值: <net.Socket> 套接字本身。

在给定套接字上启动 IPC 连接。

对 socket.connect(options[, connectListener]) 的别名，使用 { path: path } 作为 options 调用。

socket.connect(port[, host][, connectListener])#

• port <number> 客户端应连接到的端口。
• host <string> 客户端应连接到的主机。
• connectListener <Function> 是 socket.connect() 方法的通用参数。它将作为 'connect' 事件的监听器添加一次。
• 返回值: <net.Socket> 套接字本身。

在给定套接字上启动 TCP 连接。

对 socket.connect(options[, connectListener]) 的别名，使用 {port: port, host: host} 作为 options 调用。

socket.connecting#

• <boolean>

如果为 true，则已调用 socket.connect(options[, connectListener]) 且尚未完成。它将保持 true 状态，直到套接字连接，然后设置为 false 并发出 'connect' 事件。请注意，socket.connect(options[, connectListener]) 回调是 'connect' 事件的监听器。

socket.destroy([error])#

• error <Object>
• 返回值： <net.Socket>

确保此套接字上不再发生任何 I/O 活动。销毁流并关闭连接。

有关更多详细信息，请参阅 writable.destroy()。

socket.destroyed#

• <boolean> 指示连接是否已销毁。一旦连接被销毁，就无法再使用它传输任何数据。

有关更多详细信息，请参阅 writable.destroyed。

socket.destroySoon()#

在所有数据写入后销毁套接字。如果 'finish' 事件已经发出，则套接字会立即销毁。如果套接字仍然可写，它会隐式调用 socket.end()。

socket.end([data[, encoding]][, callback])#

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> 仅在数据为 string 时使用。默认值： 'utf8'。
• callback <Function> 套接字完成时的可选回调函数。
• 返回值: <net.Socket> 套接字本身。

半关闭套接字。即，它发送 FIN 数据包。服务器可能仍然会发送一些数据。

有关更多详细信息，请参阅 writable.end()。

socket.localAddress#

• <string>

远程客户端连接的本地 IP 地址的字符串表示形式。例如，在一个监听 '0.0.0.0' 的服务器上，如果一个客户端连接到 '192.168.1.1'，则 socket.localAddress 的值为 '192.168.1.1'。

socket.localPort#

• <integer>

本地端口的数字表示形式。例如，80 或 21。

socket.localFamily#

• <string>

本地 IP 族类的字符串表示形式。'IPv4' 或 'IPv6'。

socket.pause()#

• 返回值: <net.Socket> 套接字本身。

暂停读取数据。也就是说，'data' 事件将不会被发出。在限制上传速度时很有用。

socket.pending#

• <boolean>

如果套接字尚未连接，则为 true，可能是因为尚未调用 .connect()，或者因为它仍在连接过程中（参见 socket.connecting）。

socket.ref()#

• 返回值: <net.Socket> 套接字本身。

与 unref() 相反，在先前 unref 的套接字上调用 ref() 不会 允许程序在它是唯一剩余的套接字时退出（默认行为）。如果套接字是 ref 的，再次调用 ref 将不会有任何效果。

socket.remoteAddress#

• <string>

远程 IP 地址的字符串表示形式。例如，'74.125.127.100' 或 '2001:4860:a005::68'。如果套接字被销毁（例如，如果客户端断开连接），则该值可能为 undefined。

socket.remoteFamily#

• <string>

远程 IP 族类的字符串表示形式。'IPv4' 或 'IPv6'。如果套接字被销毁（例如，如果客户端断开连接），则该值可能为 undefined。

socket.remotePort#

• <integer>

远程端口的数字表示形式。例如，80 或 21。如果套接字被销毁（例如，如果客户端断开连接），则该值可能为 undefined。

socket.resetAndDestroy()#

• 返回值： <net.Socket>

通过发送 RST 数据包关闭 TCP 连接并销毁流。如果此 TCP 套接字处于连接状态，它将在连接后发送 RST 数据包并销毁此 TCP 套接字。否则，它将使用 ERR_SOCKET_CLOSED 错误调用 socket.destroy。如果这不是 TCP 套接字（例如，管道），则调用此方法将立即抛出 ERR_INVALID_HANDLE_TYPE 错误。

socket.resume()#

• 返回值: <net.Socket> 套接字本身。

在调用 socket.pause() 后恢复读取。

socket.setEncoding([encoding])#

• encoding <string>
• 返回值: <net.Socket> 套接字本身。

将套接字设置为 可读流 的编码。有关更多信息，请参阅 readable.setEncoding()。

socket.setKeepAlive([enable][, initialDelay])#

• enable <boolean> 默认值： false
• initialDelay <number> 默认值： 0
• 返回值: <net.Socket> 套接字本身。

启用/禁用保持活动功能，并可以选择设置在空闲套接字上发送第一个保持活动探测之前的初始延迟。

设置 initialDelay（以毫秒为单位）以设置接收到的最后一个数据包与第一个保持活动探测之间的延迟。将 initialDelay 设置为 0 将使该值保持为默认值（或先前）设置不变。

启用保持活动功能将设置以下套接字选项

• SO_KEEPALIVE=1
• TCP_KEEPIDLE=initialDelay
• TCP_KEEPCNT=10
• TCP_KEEPINTVL=1

socket.setNoDelay([noDelay])#

• noDelay <boolean> 默认值： true
• 返回值: <net.Socket> 套接字本身。

启用/禁用 Nagle 算法的使用。

创建 TCP 连接时，将启用 Nagle 算法。

Nagle 算法会在数据通过网络发送之前延迟数据。它试图以延迟为代价优化吞吐量。

为 noDelay 传递 true 或不传递参数将为套接字禁用 Nagle 算法。为 noDelay 传递 false 将启用 Nagle 算法。

socket.setTimeout(timeout[, callback])#

• timeout <number>
• callback <Function>
• 返回值: <net.Socket> 套接字本身。

在套接字上设置套接字在timeout毫秒的空闲时间后超时。默认情况下，net.Socket没有超时。

当空闲超时触发时，套接字将收到一个'timeout'事件，但连接不会断开。用户必须手动调用socket.end()或socket.destroy()来结束连接。

socket.setTimeout(3000);
socket.on('timeout', () => {
  console.log('socket timeout');
  socket.end();
}); copy

如果timeout为0，则禁用现有的空闲超时。

可选的callback参数将作为'timeout'事件的一次性监听器添加。

socket.timeout#

• <number> | <undefined>

由socket.setTimeout()设置的套接字超时，以毫秒为单位。如果未设置超时，则为undefined。

socket.unref()#

• 返回值: <net.Socket> 套接字本身。

在套接字上调用unref()将允许程序在这是事件系统中唯一活动的套接字时退出。如果套接字已经unrefed，再次调用unref()将不会有任何效果。

socket.write(data[, encoding][, callback])#

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> 仅在数据为string时使用。默认：utf8。
• callback <Function>
• 返回值： <boolean>

在套接字上发送数据。第二个参数指定字符串情况下的编码。它默认为 UTF8 编码。

如果所有数据都成功刷新到内核缓冲区，则返回true。如果所有或部分数据排队在用户内存中，则返回false。当缓冲区再次可用时，将发出'drain'。

可选的callback参数将在数据最终写入时执行，这可能不会立即发生。

有关更多信息，请参阅Writable流write()方法。

socket.readyState#

• <string>

此属性表示连接状态，以字符串形式表示。

• 如果流正在连接，则socket.readyState为opening。
• 如果流可读且可写，则它是open。
• 如果流可读但不可写，则它是readOnly。
• 如果流不可读且不可写，则它是writeOnly。

net.connect()#

到 net.createConnection() 的别名。

可能的签名

• net.connect(options[, connectListener])
• net.connect(path[, connectListener]) 用于 IPC 连接。
• net.connect(port[, host][, connectListener]) 用于 TCP 连接。

net.connect(options[, connectListener])#

• options <Object>
• connectListener <Function>
• 返回值： <net.Socket>

到 net.createConnection(options[, connectListener]) 的别名。

net.connect(path[, connectListener])#

• path <string>
• connectListener <Function>
• 返回值： <net.Socket>

到 net.createConnection(path[, connectListener]) 的别名。

net.connect(port[, host][, connectListener])#

• port <number>
• host <string>
• connectListener <Function>
• 返回值： <net.Socket>

到 net.createConnection(port[, host][, connectListener]) 的别名。

net.createConnection()#

一个工厂函数，它创建一个新的 net.Socket，立即使用 socket.connect() 初始化连接，然后返回开始连接的 net.Socket。

连接建立后，将在返回的套接字上发出 'connect' 事件。如果提供了最后一个参数 connectListener，它将被添加为 'connect' 事件的监听器 一次。

可能的签名

• net.createConnection(options[, connectListener])
• net.createConnection(path[, connectListener]) 用于 IPC 连接。
• net.createConnection(port[, host][, connectListener]) 用于 TCP 连接。

net.connect() 函数是此函数的别名。

net.createConnection(options[, connectListener])#

• options <Object> 必需。将传递给 new net.Socket([options]) 调用和 socket.connect(options[, connectListener]) 方法。
• connectListener <Function> net.createConnection() 函数的通用参数。如果提供，将作为 'connect' 事件的监听器添加到返回的套接字上一次。
• 返回值: <net.Socket> 用于启动连接的全新创建的套接字。

有关可用选项，请参阅 new net.Socket([options]) 和 socket.connect(options[, connectListener])。

其他选项

• timeout <number> 如果设置，将在套接字创建后但开始连接之前用于调用 socket.setTimeout(timeout)。

以下是 net.createServer() 部分中描述的回声服务器客户端的示例

const net = require('node:net');
const client = net.createConnection({ port: 8124 }, () => {
  // 'connect' listener.
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
}); copy

要连接到套接字 /tmp/echo.sock

const client = net.createConnection({ path: '/tmp/echo.sock' }); copy

net.createConnection(path[, connectListener])#

• path <string> 套接字应连接到的路径。将传递给 socket.connect(path[, connectListener])。请参阅 识别 IPC 连接的路径。
• connectListener <Function> net.createConnection() 函数的通用参数，是启动套接字上 'connect' 事件的“一次”监听器。将传递给 socket.connect(path[, connectListener])。
• 返回值: <net.Socket> 用于启动连接的全新创建的套接字。

启动 IPC 连接。

此函数使用所有选项设置为默认值创建一个新的 net.Socket，立即使用 socket.connect(path[, connectListener]) 启动连接，然后返回启动连接的 net.Socket。

net.createConnection(port[, host][, connectListener])#

• port <number> 套接字应连接到的端口。将传递给 socket.connect(port[, host][, connectListener])。
• host <string> 套接字应连接到的主机。将传递给 socket.connect(port[, host][, connectListener])。默认值： 'localhost'。
• connectListener <Function> net.createConnection() 函数的通用参数，是发起套接字上 'connect' 事件的“一次性”监听器。将传递给 socket.connect(port[, host][, connectListener])。
• 返回值: <net.Socket> 用于启动连接的全新创建的套接字。

启动 TCP 连接。

此函数创建一个新的 net.Socket，所有选项都设置为默认值，立即使用 socket.connect(port[, host][, connectListener]) 启动连接，然后返回启动连接的 net.Socket。

net.createServer([options][, connectionListener])#

• options <Object>

  • allowHalfOpen <boolean> 如果设置为 false，则套接字将在可读端结束时自动结束可写端。默认值： false。
  • highWaterMark <number> 可选地覆盖所有 net.Socket 的 readableHighWaterMark 和 writableHighWaterMark。默认值： 请参见 stream.getDefaultHighWaterMark()。
  • pauseOnConnect <boolean> 指示套接字是否应在传入连接时暂停。默认值： false。
  • noDelay <boolean> 如果设置为 true，则在收到新的传入连接后立即禁用使用 Nagle 算法。默认值： false。
  • keepAlive <boolean> 如果设置为 true，则在收到新的传入连接后立即在套接字上启用保持活动功能，类似于 socket.setKeepAlive([enable][, initialDelay]) 中所做的那样。默认值： false。
  • keepAliveInitialDelay <number> 如果设置为正数，则在空闲套接字上发送第一个保持活动探测之前设置初始延迟。默认值： 0。

• connectionListener <Function> 自动设置为 'connection' 事件的监听器。

• 返回值: <net.Server>

创建一个新的 TCP 或 IPC 服务器。

如果将allowHalfOpen设置为true，当套接字的另一端发出传输结束信号时，服务器只有在显式调用socket.end()时才会发送回传输结束信号。例如，在 TCP 上下文中，当接收到 FIN 包时，只有在显式调用socket.end()时才会发送回 FIN 包。在此之前，连接处于半关闭状态（不可读但仍可写）。有关更多信息，请参见'end'事件和RFC 1122（第 4.2.2.13 节）。

如果将pauseOnConnect设置为true，则与每个传入连接关联的套接字将被暂停，并且不会从其句柄读取任何数据。这允许在进程之间传递连接，而不会由原始进程读取任何数据。要开始从暂停的套接字读取数据，请调用socket.resume()。

服务器可以是 TCP 服务器或IPC 服务器，具体取决于它listen()的内容。

以下是一个在端口 8124 上监听连接的 TCP 回声服务器示例

const net = require('node:net');
const server = net.createServer((c) => {
  // 'connection' listener.
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
}); copy

使用telnet测试此功能

telnet localhost 8124 copy

要在套接字/tmp/echo.sock上监听

server.listen('/tmp/echo.sock', () => {
  console.log('server bound');
}); copy

使用nc连接到 Unix 域套接字服务器

nc -U /tmp/echo.sock copy

net.getDefaultAutoSelectFamily()#

获取socket.connect(options)的autoSelectFamily选项的当前默认值。初始默认值为true，除非提供命令行选项--no-network-family-autoselection。

• 返回值：<boolean> autoSelectFamily选项的当前默认值。

net.setDefaultAutoSelectFamily(value)#

设置socket.connect(options)的autoSelectFamily选项的默认值。

• value <boolean> 新的默认值。初始默认值为false。

net.getDefaultAutoSelectFamilyAttemptTimeout()#

获取socket.connect(options)的autoSelectFamilyAttemptTimeout选项的当前默认值。初始默认值为250。

• 返回值：<number> autoSelectFamilyAttemptTimeout 选项的当前默认值。

net.setDefaultAutoSelectFamilyAttemptTimeout(value)#

设置 socket.connect(options) 的 autoSelectFamilyAttemptTimeout 选项的默认值。

• value <number> 新的默认值，必须为正数。如果数字小于 10，则使用 10 作为值。初始默认值为 250。

net.isIP(input)#

• input <string>
• 返回值：<integer>

如果 input 是 IPv6 地址，则返回 6。如果 input 是没有前导零的 点分十进制表示法 的 IPv4 地址，则返回 4。否则，返回 0。

net.isIP('::1'); // returns 6
net.isIP('127.0.0.1'); // returns 4
net.isIP('127.000.000.001'); // returns 0
net.isIP('127.0.0.1/24'); // returns 0
net.isIP('fhqwhgads'); // returns 0 copy

net.isIPv4(input)#

• input <string>
• 返回值： <boolean>

如果 input 是没有前导零的 点分十进制表示法 的 IPv4 地址，则返回 true。否则，返回 false。

net.isIPv4('127.0.0.1'); // returns true
net.isIPv4('127.000.000.001'); // returns false
net.isIPv4('127.0.0.1/24'); // returns false
net.isIPv4('fhqwhgads'); // returns false copy

net.isIPv6(input)#

• input <string>
• 返回值： <boolean>

如果 input 是 IPv6 地址，则返回 true。否则，返回 false。

net.isIPv6('::1'); // returns true
net.isIPv6('fhqwhgads'); // returns false copy