网络

稳定性：2 - 稳定

node:net 模块提供了一个异步网络 API，用于创建基于流的 TCP 或 IPC 服务器（net.createServer()）和客户端 （net.createConnection()）。

可以使用以下方式访问它：

import net from 'node:net';

const net = require('node:net');

node:net 模块在 Windows 上支持使用命名管道进行 IPC，在其他 操作系统上支持 Unix 域套接字。

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

在 Unix 上，本地域也称为 Unix 域。路径是一个 文件系统路径名。当路径名的长度 大于 sizeof(sockaddr_un.sun_path) 的长度时，它将抛出错误。典型值在 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'));

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

blockList.addAddress(address, type?): void

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

blockList.addAddresses(addresses, type?): void

在单次操作中向阻止列表添加多条地址规则。

当添加大量单独地址时，这比反复调用 blockList.addAddress() 更高效，因为这些地址会在一次内部锁获取期间插入。

blockList.addCIDR(cidr): void

使用 CIDR 表示法添加一条子网规则。地址族会根据地址自动检测（如果地址包含 ':' 则为 IPv6，否则为 IPv4）。这等价于使用解析后的网络地址、 前缀长度和地址族调用 blockList.addSubnet()。

blockList.addCIDRs(cidrs): void

在一次调用中使用 CIDR 表示法添加多条子网规则。每个条目的地址族都会自动检测。 这等价于对数组中的每个元素调用 blockList.addCIDR()。

blockList.addRange(start, end, type?): void

添加一条规则以阻止从 start（包含）到 end（包含）的 IP 地址范围。

blockList.addSubnet(net, prefix, type?): void

添加一条规则以阻止指定为子网掩码的 IP 地址范围。

blockList.check(address, type?): void

如果给定的 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'));  // 输出：true
console.log(blockList.check('10.0.0.3'));  // 输出：true
console.log(blockList.check('222.111.111.222'));  // 输出：false

// IPv4 地址的 IPv6 表示法有效：
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // 输出：true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // 输出：true

blockList.clear(): void

清除 BlockList 中的所有规则。

blockList.fromJSON(value): void

稳定性：1.2 - 候选发布

const blockList = new net.BlockList();
const data = [
  'Subnet: IPv4 192.168.1.0/24',
  'Address: IPv4 10.0.0.5',
  'Range: IPv4 192.168.2.1-192.168.2.10',
  'Range: IPv4 10.0.0.1-10.0.0.10',
];
blockList.fromJSON(data);
blockList.fromJSON(JSON.stringify(data));

• value Blocklist.rules

BlockList.isBlockList(value): void

• 类型：string[]

一个冻结的 CIDR 字符串数组，表示私有、回环和链路本地 IP 地址范围。可以将其传递给 blockList.addCIDRs()，以快速将所有不可路由的地址范围添加到阻止列表中。

包含的范围如下：

• 10.0.0.0/8 — RFC 1918 私有 IPv4
• 172.16.0.0/12 — RFC 1918 私有 IPv4
• 192.168.0.0/16 — RFC 1918 私有 IPv4
• 127.0.0.0/8 — IPv4 回环
• ::1/128 — IPv6 回环
• 169.254.0.0/16 — IPv4 链路本地
• fe80::/10 — IPv6 链路本地
• fc00::/7 — IPv6 唯一本地地址（ULA）

const blockList = new net.BlockList();
blockList.addCIDRs(net.BlockList.PRIVATE_RANGES);

console.log(blockList.check('10.0.0.1'));      // 输出：true
console.log(blockList.check('127.0.0.1'));     // 输出：true
console.log(blockList.check('8.8.8.8'));       // 输出：false

blockList.removeAddress(address, type?): void

移除之前通过 blockList.addAddress() 添加的规则。 地址必须与添加规则时使用的值完全匹配。如果指定的地址不存在，则不执行任何操作。

blockList.removeCIDR(cidr): void

使用 CIDR 表示法移除一条子网规则。地址族会根据地址自动检测。 这等价于使用解析后的网络地址、前缀长度和地址族调用 blockList.removeSubnet()。如果指定的子网不存在，则不执行任何操作。

blockList.removeRange(start, end, type?): void

移除之前通过 blockList.addRange() 添加的规则。start 和 end 地址必须与添加规则时使用的值完全匹配。 如果指定的范围不存在，则不执行任何操作。

blockList.removeSubnet(net, prefix, type?): void

移除之前通过 blockList.addSubnet() 添加的规则。 网络地址和前缀必须与添加规则时使用的值完全匹配。 如果指定的子网不存在，则不执行任何操作。

• 类型：string[]

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

• 类型：number

阻止列表中的规则数量。这等价于 blockList.rules.length，但不会分配规则数组。

blockList.toJSON(): void

稳定性：1.2 - 候选发布

• 返回 Blocklist.rules。

new net.SocketAddress(options?): void

• 类型：string

• 类型：string 'ipv4' 或 'ipv6'。

• 类型：number

• 类型：number

SocketAddress.parse(input): void

• 继承：EventEmitter

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

一个正在监听的 TCP net.Server 可以通过将其列入 worker_threads 的 postMessage() 调用中的 transferList，转移到工作线程。 这会将底层监听套接字移到接收线程，在那里它会继续 接受连接。参见 [将 TCP 句柄转移到其他线程][]。

new net.Server(options?, connectionListener?): void

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

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

• 类型：net.Socket 连接对象

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

• 类型：Error

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

在调用 server.listen() 后，服务器完成绑定时触发。

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

server.address(): void

• 返回：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) => {
  // 在这里处理错误。
  throw err;
});

// 获取一个任意未使用的端口。
server.listen(() => {
  console.log('opened server on', server.address());
});

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

server.close(callback?): void

停止服务器接受新连接，并保留现有连接。此函数是异步的，当所有连接都结束且服务器发出 'close' 事件时，服务器最终会关闭。可选的 callback 会在 'close' 事件发生后被调用。与该事件不同的是，如果服务器在关闭时并未处于打开状态，它将以一个 Error 作为唯一参数被调用。

server[Symbol.asyncDispose](): void

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

server[Symbol.asyncIterator](): void

稳定性：1 - 实验性

• 返回：AsyncIterator 一个异步迭代器，为每个传入的 net.Socket 生成值。

返回一个用于迭代服务器传入连接的异步迭代器，使其可以使用 for await...of 进行消费，作为 'connection' 事件的替代方案。当服务器发出 'close' 事件时，迭代结束；当服务器发出 'error' 事件时，迭代将被拒绝。

只有在当前迭代的主体完成等待后，循环才会继续处理下一个连接，因此连接处理应分派到单独的异步任务中，而不应直接内联等待。否则，连接将被串行处理：每个连接都要等待前一个连接被完全处理。

import { createServer } from 'node:net';

const server = createServer().listen(8124);

async function handleConnection(socket) {
  // ...处理连接，并按需等待。
  socket.end('hello world!');
}

for await (const socket of server) {
  // 将处理分派到单独的任务中，使循环继续接受连接，
  // 而不是将它们串行处理。
  handleConnection(socket);
}

循环主体运行期间，服务器不会停止接受连接，因此处理速度低于连接速率的消费者可能会无限制地缓存连接。使用 server.maxConnections 来限制并发数。

server.getConnections(callback): void

异步获取服务器上的并发连接数。当套接字被发送到子进程时也能正常工作。

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

server.listen(): void

启动一个监听连接的服务器。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('地址正在使用中，正在重试...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

server.listen(handle, backlog?, callback?): void

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

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

当 handle 是 BoundSocket 时，服务器会接管该已绑定的 套接字并开始在其上监听。接管会消耗该已绑定套接字（参见 所有权转移）。

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

server.listen(options, callback?): void

如果指定了 handle，服务器会接管该预绑定套接字。否则，如果 指定了 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,
});

当 exclusive 处于 true 状态且底层句柄为共享时， 可能会出现多个工作进程使用不同的 backlog 查询同一个句柄的情况。 在这种情况下，将使用传递给主进程的第一个 backlog。

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

如果启用了 signal 选项，在对应的 AbortController 上调用 .abort() 类似于在服务器上调用 .close()：

const controller = new AbortController();
server.listen({
  host: 'localhost',
  port: 80,
  signal: controller.signal,
});
// 稍后，当你想关闭服务器时。
controller.abort();

server.listen(path, backlog?, callback?): void

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

server.listen(port?, host?, backlog?, callback?): void

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

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

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

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

• 类型：boolean 指示服务器当前是否正在监听连接。

• 类型：integer

当连接数达到 server.maxConnections 阈值时：

1. 如果进程未在集群模式下运行，Node.js 将关闭该连接。

2. 如果进程在集群模式下运行，Node.js 默认会将该连接路由到另一个工作进程。若要改为关闭连接，请将 server.dropMaxConnection 设置为 true。

不建议在套接字已通过 child_process.fork() 发送给子进程后再使用此选项。

• 类型：boolean

将此属性设置为 true，以便在连接数达到 server.maxConnections 阈值后开始关闭连接。此设置仅在集群模式下有效。

server.ref(): void

• 返回：net.Server

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

server.unref(): void

• 返回：net.Server

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

• 继承：stream.Duplex

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

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

Node.js 也可以创建该对象，并在接收到连接时将其传递给用户。例如，它会被传递给 net.Server 上触发的 'connection' 事件的监听器，因此用户可以使用它与客户端进行交互。

一个已连接的 TCP net.Socket 可以通过将其列入 worker_threads 的 postMessage() 调用的 transferList 中，移动到另一个线程。传输后，源 socket 会在发送线程上被销毁（后续使用会失败并返回 ERR_STREAM_DESTROYED，而不是静默丢弃数据），并且该 socket 会继续在接收线程上工作。这使得可以在一个线程上接受连接，然后将它们分发到一个 worker 线程池中，例如在 worker 线程之上构建类似 node:cluster 的模型。

该 socket 必须是刚刚接受或创建的 TCP 连接：它仍必须附加到一个活动句柄上，不能处于连接中或已销毁状态，也不能已经开始读取或包含缓冲数据。否则，postMessage() 会抛出 ERR_WORKER_HANDLE_NOT_TRANSFERABLE。目前仅支持 TCP socket。

const net = require('node:net');
const { Worker } = require('node:worker_threads');

// worker.js 接收 `{ socket }` 消息并处理每个连接。
const worker = new Worker('./worker.js');

const server = net.createServer((socket) => {
  // 将新接受的连接交给 worker 线程。
  worker.postMessage({ socket }, [socket]);
});
server.listen(8000);

监听中的 net.Server 也可以用相同的方式传递，这会将监听 socket 本身（以及其待处理的 accept 队列）移动到接收线程。

new net.Socket(options?): void

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

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

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

在 Socket 连接成功建立时发出。 详见 net.createConnection().

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

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

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

• 类型：Buffer | string

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

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

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

另见：socket.write() 的返回值。

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

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

• 类型：Error

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

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

在 Socket 准备好使用时发出。

在 'connect' 之后立即触发。

如果 Socket 因不活动而超时时发出。这仅用于通知 Socket 处于空闲状态。用户必须手动关闭连接。

另见：socket.setTimeout()。

socket.address(): void

• 返回：Object

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

• 类型：string[]

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

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

稳定性：0 - 已废弃：改用 writable.writableLength。

• 类型：integer

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

net.Socket 具有 socket.write() 始终有效的属性。这是为了帮助用户快速上手。计算机无法总是跟上写入 Socket 的数据量。网络连接可能只是太慢。Node.js 将在内部队列化写入 Socket 的数据，并在可能时通过线路发送出去。

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

• 类型：整数

接收的字节数。

• 类型：integer

发送的字节数。

socket.connect(): void

在给定的 Socket 上发起连接。

可能的签名：

• socket.connect(options[, connectListener])
• socket.connect(path[, connectListener]) 用于 IPC 连接。
• socket.connect(port[, host][, connectListener]) 用于 TCP 连接。
• 返回：net.Socket Socket 本身。

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

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

socket.connect(options, connectListener?): void

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

对于 TCP 连接，可用的 options 包括：

对于 IPC 连接，可用的 options 包括：

socket.connect(path, connectListener?): void

在给定的 Socket 上发起 IPC 连接。

别名于 socket.connect(options[, connectListener]) 调用时 { path: path } 作为 options。

socket.connect(port, host?, connectListener?): void

在给定的 Socket 上发起 TCP 连接。

别名于 socket.connect(options[, connectListener]) 调用时 {port: port, host: host} 作为 options。

• 类型：boolean

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

socket.destroy(error?): void

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

详见 writable.destroy() 以获取更多详情。

• 类型：boolean 指示连接是否已销毁。一旦连接被销毁，不能再使用它传输任何数据。

详见 writable.destroyed 以获取更多详情。

socket.destroySoon(): void

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

socket.end(data?, encoding?, callback?): void

半关闭 Socket。即，它发送一个 FIN 包。服务器可能仍会发送一些数据。

详见 writable.end() 以获取更多详情。

• 类型：string

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

• 类型：integer

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

• 类型：string

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

socket.pause(): void

• 返回：net.Socket Socket 本身。

暂停数据读取。即，'data' 事件将不会发出。
可用于限制上传。

• 类型：boolean

如果 Socket 尚未连接，则为 true，要么是因为 .connect() 尚未调用，要么是因为它仍在连接过程中（详见 socket.connecting）。

socket.ref(): void

• 返回：net.Socket Socket 本身。

unref() 的反义词，在先前调用过 unref 的 Socket 上调用 ref() 将 不 允许程序退出，如果它是唯一剩下的 Socket（默认行为）。如果 Socket 已调用 ref，再次调用 ref 将无效。

• 类型：string

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

• 类型：string

远程 IP 家族的字符串表示。'IPv4' 或 'IPv6'。如果 Socket 已销毁（例如，如果客户端断开连接），值可能为 undefined。

• 类型：integer

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

• 类型：net.Server | null

接受该套接字的服务器的引用。对于未由服务器接受的套接字，此值为 null。

socket.resetAndDestroy(): void

• 返回：net.Socket

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

socket.resume(): void

• 返回：net.Socket Socket 本身。

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

socket.setEncoding(encoding?): void

将 Socket 的编码设置为 可读流。详见 readable.setEncoding() 以获取更多信息。

socket.setKeepAlive(): void

启用/禁用 keep-alive 功能，并可选择配置 keepalive 探测时序。返回该 socket 本身。

可能的签名：

• socket.setKeepAlive([options])
• socket.setKeepAlive([enable][, initialDelay][, interval][, count])

启用 keep-alive 会设置在空闲 socket 上发送第一条 keepalive 探测之前的初始延迟。

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

设置 interval（以毫秒为单位）可设置 keepalive 探测开始后连续探测之间的延迟（TCP_KEEPINTVL）。将 count 设置为在连接被断开前发送但未得到确认的探测次数（TCP_KEEPCNT）。这两个参数仅在启用 keep-alive 时生效。省略 interval 或 count 时，分别使用 1000 毫秒和 10 的默认值。与 initialDelay 一样，非正的 interval 或 count 会使相应的系统默认值保持不变。

initialDelay 和 interval 以毫秒为单位指定，但底层 socket 选项会按整秒配置；在应用之前，这些值会除以 1000 并向下取整。

启用 keep-alive 功能将设置以下 socket 选项：

• SO_KEEPALIVE=1
• TCP_KEEPIDLE=initialDelay / 1000
• TCP_KEEPCNT=count
• TCP_KEEPINTVL=interval / 1000

在早于 build 1709 的 Windows 版本上，keep-alive 通过 SIO_KEEPALIVE_VALS 配置，它没有探测计数字段，因此在这些平台上会忽略 count。

socket.setKeepAlive(options?): void

使用选项对象配置 keep-alive。有关每个属性的说明，请参见 socket.setKeepAlive()。

socket.setKeepAlive({ enable: true, initialDelay: 1000, interval: 1000, count: 10 });

socket.setKeepAlive(enable?, initialDelay?, interval?, count?): void

使用位置参数配置保持活动。有关每个参数的说明，请参见 socket.setKeepAlive().

socket.setNoDelay(noDelay?): void

启用/禁用 Nagle 算法。

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

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

为 noDelay 传递 true 或不传递参数将禁用 Socket 的 Nagle 算法。为 noDelay 传递 false 将启用 Nagle 算法。

socket.setTimeout(timeout, callback?): void

设置 Socket 在 Socket 上不活动 timeout 毫秒后超时。默认情况下，net.Socket 没有超时。

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

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

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

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

socket.getTypeOfService(): void

• 返回：integer 当前的 TOS 值。

返回此 Socket 的 IPv4 数据包的当前服务类型 (TOS) 字段或 IPv6 数据包的流量类别。

setTypeOfService() 可以在 Socket 连接之前调用；值将被缓存并在 Socket 建立连接时应用。 getTypeOfService() 甚至在连接之前也会返回当前设置的值。

在某些平台（例如，Linux）上，某些 TOS/ECN 位可能被屏蔽或忽略，并且行为在 IPv4 和 IPv6 或双栈 Socket 之间可能不同。调用者应验证特定于平台的语义。

socket.setTypeOfService(tos): void

为从此 Socket 发送的 IPv4 数据包设置服务类型（TOS）字段，或为 IPv6 数据包设置流量类别。此功能可用于设置网络流量的优先级。

setTypeOfService() 可以在 Socket 连接之前调用；该值会被缓存，并在 Socket 建立连接时应用。 即使在连接之前，getTypeOfService() 也会返回当前设置。

在某些平台（例如 Linux）上，某些 TOS/ECN 位可能会被屏蔽或忽略，并且 IPv4 和 IPv6 或双栈 Socket 之间的行为可能有所不同。调用方应确认特定平台上的语义。

• 类型：number | undefined

由 socket.setTimeout() 设置的 Socket 超时（毫秒）。
如果未设置超时，则为 undefined。

socket.unref(): void

• 返回：net.Socket Socket 本身。

在 Socket 上调用 unref() 将允许程序退出，如果这是事件系统中唯一活动的 Socket。如果 Socket 已经 unref，再次调用 unref() 将无效。

socket.write(data, encoding?, callback?): void

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

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

可选的 callback 参数将在数据最终写出时执行，这可能不是立即的。

详见 Writable 流 write() 方法以获取更多信息。

• 类型：string

此属性表示连接的状态（字符串）。

• 如果套接字正在连接，则 socket.readyState 为 opening。
• 如果套接字可读且可写，则为 open。
• 如果套接字可读但不可写，则为 readOnly。
• 如果套接字不可读但可写，则为 writeOnly。
• 否则为 closed。

允许同步创建一个预绑定的套接字，之后可以将其传递给 listen() 或 new net.Socket()。对于 listen()，这可实现同步端口预留；而对于 new net.Socket()，它允许通过 bind(2) 语义来控制本地出站端口/IP。

BoundSocket 可以绑定 TCP 端点（host 或 port），也可以绑定 Unix 域/命名管道端点（path）；两者互斥。对于 path，文件系统条目会在构造函数中预留，因此诸如 EADDRINUSE 之类的冲突会像 TCP 绑定一样同步抛出。在 Linux 上，path 开头的 '\0' 会选择抽象命名空间（不创建文件系统条目）；在其他平台上使用抽象路径会抛出 ERR_INVALID_ARG_VALUE。

接管会转移套接字的所有权；此后调用 address() 和 close() 会抛出 ERR_SOCKET_HANDLE_ADOPTED。从未被接管的句柄必须关闭，以避免套接字泄漏。关闭管道 BoundSocket 会移除其文件系统条目；抽象绑定和 TCP 绑定没有需要移除的条目。

当绑定到源 path 的管道 BoundSocket 作为客户端被接管后，连接成功时，该路径会作为套接字的 localAddress 报告。

当被接管的 BoundSocket 连接到数字 IP 字面量时，会同步发出 connect(2)，因此 socket.connect() 返回后即可解析 socket.localAddress。连接失败仍会通过延迟触发的 'error' 事件报告。

import net from 'node:net';

const bound = new net.BoundSocket();
const { port } = bound.address();
console.log(`为服务器预留端口 ${port}`);

const server = net.createServer();
server.listen(bound); // 作为服务器接管，或者改为传给 new net.Socket()。

new net.BoundSocket(options?): void

boundSocket.address(): void

• 返回值：Object | string 对于 TCP 绑定，返回一个包含 address、family 和 port 属性的对象，类似 server.address() 的返回值。对于管道绑定，返回已绑定的路径字符串，类似管道服务器中 server.address() 的返回值。

返回已绑定的本地地址。当使用 port: 0 绑定时，port 是操作系统分配的临时端口。

当套接字使用 path 绑定（Unix 域套接字或 Windows 命名管道）时为 true，TCP 绑定时为 false。net.BoundSocket.prototype 上存在此 getter 也可用作探测是否支持 path 的能力检测。

boundSocket.fd(): void

• 返回：integer 底层操作系统文件描述符；在不向套接字暴露文件描述符的平台上（例如 Windows），则为 -1。

返回已绑定套接字的文件描述符。其所有权仍归 BoundSocket 所有，因此调用方不得关闭该描述符。 该描述符仅在句柄被接管之前可用；之后它属于接管它的 net.Server 或 net.Socket，并且 fd() 会抛出 ERR_SOCKET_HANDLE_ADOPTED。

boundSocket.close(): void

释放已绑定的套接字。仅在句柄从未被接管时需要。

如果句柄尚未被接管或关闭，则关闭它；否则不执行任何操作。

net.connect(): void

别名于 net.createConnection()。

可能的签名：

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

net.connect(options, connectListener?): void

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

net.connect(path, connectListener?): void

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

net.connect(port, host?, connectListener?): void

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

net.createConnection(): void

这是一个工厂函数，它创建一个新的 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?): void

可用选项参见 new net.Socket([options]) 和 socket.connect(options[, connectListener])。

其他选项：

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

import net from 'node:net';
const client = net.createConnection({ port: 8124 }, () => {
  // `'connect'` 监听器。
  console.log('已连接到服务器！');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('已与服务器断开连接');
});

const net = require('node:net');
const client = net.createConnection({ port: 8124 }, () => {
  // `'connect'` 监听器。
  console.log('已连接到服务器！');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('已与服务器断开连接');
});

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

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

以下是使用 port 和 onread 选项的客户端示例。 在这种情况下，onread 选项将仅用于调用 new net.Socket([options])，而 port 选项将用于 调用 socket.connect(options[, connectListener])。

import net from 'node:net';
import { Buffer } from 'node:buffer';
net.createConnection({
  port: 8124,
  onread: {
    // 为每次从套接字读取重用 4KiB Buffer。
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // 接收到的数据在 `buf` 中从 0 到 `nread` 可用。
      console.log(buf.toString('utf8', 0, nread));
    },
  },
});

const net = require('node:net');
net.createConnection({
  port: 8124,
  onread: {
    // 为每次从套接字读取重用 4KiB Buffer。
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // 接收到的数据在 `buf` 中从 0 到 `nread` 可用。
      console.log(buf.toString('utf8', 0, nread));
    },
  },
});

发起一个 IPC 连接。

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

发起一个 TCP 连接。

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

net.createServer(options?, connectionListener?): void

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

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

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

服务器可以是 TCP 服务器或 IPC 服务器，取决于它调用 listen() 时使用的方式。

这是一个监听端口 8124 连接的 TCP 回显服务器示例：

import net from 'node:net';
const server = net.createServer((c) => {
  // `'connection'` 监听器。
  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');
});

const net = require('node:net');
const server = net.createServer((c) => {
  // `'connection'` 监听器。
  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');
});