Node.js v26.0.0 文档

Net#

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

它可以通过以下方式访问

import net from 'node:net';
const net = require('node:net');
copy

IPC 支持#

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

标识 IPC 连接的路径#

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'));
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[]>

添加到黑名单的规则列表。

BlockList.isBlockList(value)#

• value <any> 任何 JS 值
• 如果 value 是一个 net.BlockList，则返回 true。

blockList.fromJSON(value)#

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));
copy

• value Blocklist.rules

blockList.toJSON()#

• 返回 Blocklist.rules

类: 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> IPv6 流标签，仅在 family 为 'ipv6' 时使用。
• port <number> IP 端口。

socketaddress.address#

• 类型：<string>

socketaddress.family#

• 类型: <string> 'ipv4' 或 'ipv6'。

socketaddress.flowlabel#

• 类型：<number>

socketaddress.port#

• 类型：<number>

SocketAddress.parse(input)#

• input <string> 包含 IP 地址和可选端口的输入字符串，例如 123.1.2.3:1234 或 [1::1]:1234。
• 返回: <net.SocketAddress> 如果解析成功，则返回 SocketAddress。否则返回 undefined。

类: 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

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

server.close([callback])#

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

停止服务器接受新连接并保持现有连接。此函数是异步的，当所有连接结束后，服务器最终关闭并触发 'close' 事件。一旦 'close' 事件发生，将调用可选的 callback。与该事件不同，如果服务器在关闭时未打开，它将以 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> 必需。支持以下属性
  • backlog <number> server.listen() 函数的通用参数。
  • exclusive <boolean> 默认值: false
  • host <string>
  • ipv6Only <boolean> 对于 TCP 服务器，将 ipv6Only 设置为 true 将禁用双栈支持，即绑定到主机 :: 不会使 0.0.0.0 被绑定。 默认值: false。
  • reusePort <boolean> 对于 TCP 服务器，将 reusePort 设置为 true 允许同一主机上的多个套接字绑定到同一端口。传入连接由操作系统分发到监听套接字。此选项仅在某些平台上可用，例如 Linux 3.9+、DragonFlyBSD 3.6+、FreeBSD 12.0+、Solaris 11.4 和 AIX 7.2.5+。在不支持的平台上，此选项会引发错误。 默认值: false。
  • path <string> 如果指定了 port，则将被忽略。参见 标识 IPC 连接的路径。
  • port <number>
  • readableAll <boolean> 对于 IPC 服务器，使管道对所有用户可读。 默认值: false。
  • signal <AbortSignal> 可用于关闭监听服务器的 AbortSignal。
  • writableAll <boolean> 对于 IPC 服务器，使管道对所有用户可写。 默认值: false。
• 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 且底层句柄被共享时，多个工作进程可能会使用不同的积压查询句柄。在这种情况下，将使用传递给主进程的第一个 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 或为 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>

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

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

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

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

server.dropMaxConnection#

• 类型：<boolean>

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

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> 可用的选项有
  • allowHalfOpen <boolean> 如果设置为 false，则当可读端结束时，套接字将自动结束可写端。有关详细信息，请参阅 net.createServer() 和 'end' 事件。 默认值: false。
  • blockList <net.BlockList> blockList 可用于禁用对特定 IP 地址、IP 范围或 IP 子网的出站访问。
  • fd <number> 如果指定，则包装给定文件描述符的现有套接字，否则将创建一个新套接字。
  • keepAlive <boolean> 如果设置为 true，则在连接建立后立即在套接字上启用 keep-alive 功能，类似于 socket.setKeepAlive() 中的操作。 默认值: false。
  • keepAliveInitialDelay <number> 如果设置为正数，它会设置在空闲套接字上发送第一个 keepalive 探测之前的初始延迟。默认值： 0。
  • noDelay <boolean> 如果设置为 true，则在套接字建立后立即禁用 Nagle 算法的使用。 默认值: false。
  • onread <Object> 如果指定，传入的数据将存储在单个 buffer 中，并在数据到达套接字时传递给提供的 callback。这将导致流功能无法提供任何数据。套接字将照常触发诸如 'error'、'end' 和 'close' 等事件。诸如 pause() 和 resume() 之类的方法也将按预期运行。
    • buffer <Buffer> | <Uint8Array> | <Function> 用于存储传入数据的可重用内存块或返回此类内存块的函数。
    • callback <Function> 此函数为每个传入的数据块调用。两个参数传递给它：写入 buffer 的字节数和对 buffer 的引用。从此函数返回 false 以隐式 pause() 套接字。此函数将在全局上下文中执行。
  • readable <boolean> 当传递 fd 时允许在套接字上读取，否则忽略。 默认值: false。
  • signal <AbortSignal> 可用于销毁套接字的 Abort 信号。
  • typeOfService <number> 初始服务类型 (TOS) 值。
  • writable <boolean> 当传递 fd 时允许在套接字上写入，否则忽略。 默认值: false。
• 返回: <net.Socket>

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

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

事件: 'close'#

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

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

事件：'connect'#

当套接字连接成功建立时触发。参见 net.createConnection()。

事件: 'connectionAttempt'#

• ip <string> 套接字试图连接的 IP。
• port <number> 套接字试图连接的端口。
• family <number> IP 的家族。IPv6 为 6，IPv4 为 4。

当开始新的连接尝试时触发。如果 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 的家族。IPv6 为 6，IPv4 为 4。

当连接尝试超时时触发。仅当 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 有

• autoSelectFamily <boolean>: 如果设置为 true，则启用一种松散实现 RFC 8305 第 5 节的家族自动检测算法。传递给 lookup 的 all 选项设置为 true，套接字尝试按顺序连接到所有获得的 IPv6 和 IPv4 地址，直到建立连接。首先尝试第一个返回的 AAAA 地址，然后是第一个返回的 A 地址，然后是第二个返回的 AAAA 地址，依此类推。在超时并尝试下一个地址之前，每次连接尝试（最后一次除外）都会被授予 autoSelectFamilyAttemptTimeout 选项指定的时间量。如果 family 选项不为 0 或设置了 localAddress，则忽略此项。如果至少有一个连接成功，则不会触发连接错误。如果所有连接尝试都失败，则会触发一个包含所有失败尝试的单一 AggregateError。 默认值: net.getDefaultAutoSelectFamily()。
• autoSelectFamilyAttemptTimeout <number>: 使用 autoSelectFamily 选项时，在尝试下一个地址之前等待连接尝试完成的时间量（以毫秒为单位）。如果设置为小于 10 的正整数，则将使用值 10。 默认值: net.getDefaultAutoSelectFamilyAttemptTimeout()。
• family <number>: IP 栈版本。必须为 4、6 或 0。值 0 表示允许 IPv4 和 IPv6 地址。 默认值: 0。
• hints <number> 可选的 dns.lookup() 提示。
• host <string> 套接字应连接的主机。 默认值: 'localhost'。
• localAddress <string> 套接字应从中连接的本地地址。
• localPort <number> 套接字应从中连接的本地端口。
• lookup <Function> 自定义查找函数。默认值： dns.lookup()。
• port <number> 必需。套接字应连接的端口。

对于 IPC 连接，可用的 options 有

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

socket.connect(path[, connectListener])#

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

在给定套接字上发起 IPC 连接。

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

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

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

在给定套接字上发起 TCP 连接。

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

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> 仅在 data 为 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> 套接字本身。

启用/禁用 keep-alive 功能，并可选地设置在空闲套接字上发送第一个 keepalive 探测之前的初始延迟。

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

启用 keep-alive 功能将设置以下套接字选项

• 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.getTypeOfService()#

• 返回: <integer> 当前 TOS 值。

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

setTypeOfService() 可以在套接字连接之前调用；该值将被缓存，并在套接字建立连接时应用。getTypeOfService() 将返回当前设置的值，即使在连接之前也是如此。

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

socket.setTypeOfService(tos)#

• tos <integer> 要设置的 TOS 值 (0-255)。
• 返回: <net.Socket> 套接字本身。

设置从该套接字发送的 IPv4 数据包的服务类型 (TOS) 字段或 IPv6 数据包的流量类别。这可用于优先处理网络流量。

setTypeOfService() 可以在套接字连接之前调用；该值将被缓存，并在套接字建立连接时应用。getTypeOfService() 将返回当前设置的值，即使在连接之前也是如此。

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

socket.timeout#

• 类型：<number> | <undefined>

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

socket.unref()#

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

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

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

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> 仅在 data 为 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() 部分中描述的回显服务器客户端的示例

import net from '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');
});
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

以下是一个使用 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: {
    // 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));
    },
  },
});
const net = require('node:net');
net.createConnection({
  port: 8124,
  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

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()。
  • keepAlive <boolean> 如果设置为 true，则在收到新的传入连接后立即在套接字上启用 keep-alive 功能，类似于 socket.setKeepAlive() 中的操作。默认值: false。
  • keepAliveInitialDelay <number> 如果设置为正数，它会设置在空闲套接字上发送第一个 keepalive 探测之前的初始延迟。默认值： 0。
  • noDelay <boolean> 如果设置为 true，则在收到新的传入连接后立即禁用 Nagle 算法。默认值: false。
  • pauseOnConnect <boolean> 指示传入连接时是否应暂停套接字。默认值: false。
  • blockList <net.BlockList> blockList 可用于禁止对特定 IP 地址、IP 范围或 IP 子网的入站访问。如果服务器位于反向代理、NAT 等之后，则此功能不起作用，因为与黑名单校验的地址是代理的地址或 NAT 指定的地址。

• 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 回显服务器示例

import net from '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');
});
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> 新的默认值。初始默认值为 true，除非提供了命令行选项 --no-network-family-autoselection。

net.getDefaultAutoSelectFamilyAttemptTimeout()#

获取 socket.connect(options) 的 autoSelectFamilyAttemptTimeout 选项的当前默认值。初始默认值为 500 或通过命令行选项 --network-family-autoselection-attempt-timeout 指定的值。

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

net.setDefaultAutoSelectFamilyAttemptTimeout(value)#

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

• value <number> 新的默认值，必须为正数。如果该数字小于 10，则改用 10。初始默认值为 250 或通过命令行选项 --network-family-autoselection-attempt-timeout 指定的值。

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