Node.js v24.0.0 文档

识别 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

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。

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>

SocketAddress.parse(input)#

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

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>

如果侦听 IP 套接字（用于查找在获取 OS 分配的地址时分配的端口），则返回操作系统报告的已绑定的 address、地址 family 名称和服务器的 port： { 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' 事件时，服务器最终关闭。 一旦 '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 参数来指定挂起连接队列的最大长度。 实际长度将由操作系统通过诸如 Linux 上的 tcp_max_syn_backlog 和 somaxconn 之类的 sysctl 设置来确定。 此参数的默认值为 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({
  host: 'localhost',
  port: 80,
  exclusive: true,
}); copy

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.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() 将不起作用。

new net.Socket([options])#

• options <Object> 可用选项有
  • allowHalfOpen <boolean> 如果设置为 false，则当可读端结束时，套接字将自动结束可写端。 有关详细信息，请参见 net.createServer() 和 'end' 事件。默认值: false。
  • fd <number> 如果指定，则使用给定的文件描述符包装现有套接字，否则将创建一个新的套接字。
  • onread <Object> 如果指定，传入的数据存储在单个 buffer 中，并在数据到达套接字时传递给提供的 callback。 这将导致流式传输功能不提供任何数据。 套接字将像往常一样发出 'error'、'end' 和 'close' 等事件。 pause() 和 resume() 等方法的行为也将符合预期。
    • buffer <Buffer> | <Uint8Array> | <Function> 用于存储传入数据的可重用内存块，或返回此类内存块的函数。
    • callback <Function> 每次传入数据块时都会调用此函数。 两个参数传递给它：写入 buffer 的字节数和对 buffer 的引用。 从此函数返回 false 以隐式 pause() 套接字。 此函数将在全局上下文中执行。
  • readable <boolean> 当传递 fd 时，允许在 socket 上进行读取，否则忽略。默认值: false。
  • signal <AbortSignal> 可用于销毁 socket 的 Abort 信号。
  • writable <boolean> 当传递 fd 时，允许在 socket 上进行写入，否则忽略。默认值: false。
• 返回值: <net.Socket>

创建一个新的 socket 对象。

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

事件: 'close'#

• hadError <boolean> 如果 socket 有传输错误，则为 true。

socket 完全关闭后触发一次。参数 hadError 是一个布尔值，指示 socket 是否由于传输错误而关闭。

事件: 'connect'#

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

事件: 'connectionAttempt'#

• ip <string> socket 尝试连接到的 IP。
• port <number> socket 尝试连接到的端口。
• family <number> IP 的 family。对于 IPv6，它可以是 6，对于 IPv4，它可以是 4。

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

事件: 'connectionAttemptFailed'#

• ip <string> socket 尝试连接到的 IP。
• port <number> socket 尝试连接到的端口。
• family <number> IP 的 family。对于 IPv6，它可以是 6，对于 IPv4，它可以是 4。
• error <Error> 与失败关联的错误。

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

事件: 'connectionAttemptTimeout'#

• ip <string> socket 尝试连接到的 IP。
• port <number> socket 尝试连接到的端口。
• family <number> IP 的 family。对于 IPv6，它可以是 6，对于 IPv4，它可以是 4。

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

事件: 'data'#

• <Buffer> | <string>

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

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

事件: 'drain'#

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

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

事件: 'end'#

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

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

事件: 'error'#

• <Error>

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

事件: 'lookup'#

在解析主机名之后但在连接之前触发。 不适用于 Unix socket。

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

事件: 'ready'#

当 socket 准备好使用时触发。

紧接在 'connect' 之后触发。

事件: 'timeout'#

如果 socket 因不活动而超时，则触发。 这仅用于通知 socket 已空闲。 用户必须手动关闭连接。

另请参见：socket.setTimeout()。

socket.address()#

• 返回值: <Object>

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

socket.autoSelectFamilyAttemptedAddresses#

• <string[]>

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

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

socket.bufferSize#

• <integer>

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

net.Socket 具有 socket.write() 始终有效的属性。 这是为了帮助用户快速启动并运行。 计算机并非总是能够跟上写入 socket 的数据量。 网络连接可能太慢。 Node.js 将在内部将写入 socket 的数据排队，并在可能的情况下通过线路发送出去。

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

socket.bytesRead#

• <integer>

接收到的字节数。

socket.bytesWritten#

• <integer>

发送的字节数。

socket.connect()#

在给定的 socket 上启动连接。

可能的签名

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

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

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

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> 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> socket 本身。

暂停读取数据。 也就是说，不会发出 'data' 事件。 用于限制上传。

socket.pending#

• <boolean>

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

socket.ref()#

• 返回值: <net.Socket> 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 本身。

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

socket.setEncoding([encoding])#

• encoding <string>
• 返回值: <net.Socket> socket 本身。

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

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

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

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

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

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

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

socket.setNoDelay([noDelay])#

• noDelay <boolean> 默认值: true
• 返回值: <net.Socket> socket 本身。

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

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

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

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

socket.setTimeout(timeout[, callback])#

• timeout <number>
• callback <Function>
• 返回值: <net.Socket> 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> 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(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(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'事件的 "once" 侦听器。 将传递给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' 事件的 "once" 监听器。 将被传递给 socket.connect(port[, host][, connectListener])。
• 返回: <net.Socket> 用于启动连接的新创建的套接字。

启动 TCP 连接。

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