Node.js v10.8.0 文档

目录

net (网络)#

查看英文版参与翻译

稳定性: 2 - 稳定

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

通过以下方式引入:

const net = require('net');

IPC Support#

查看英文版参与翻译

net 模块在 Windows 上支持命名管道 IPC，在其他操作系统上支持 UNIX 域套接字。

Identifying paths for IPC connections#

查看英文版参与翻译

net.connect(), net.createConnection(), server.listen() 和 socket.connect() 使用一个 path 参数来识别 IPC 端点。

在 UNIX 上，本地域也称为 UNIX 域。参数 path 是文件系统路径名。它被从 sizeof(sockaddr_un.sun_path) - 1 处被截断，其长度因操作系统不同而在 91 至 107 字节之间变化。典型值在 Linux 上为 107，在 macOS 上为 103。该路径受到与创建文件相同的命名约定和权限检查。它将在文件系统中可见，并且将持续到取消链接的时候。

在 Windows 上，本地域通过命名管道实现。路径必须是以 \\?\pipe\ 或 \\.\pipe\ 为入口。路径允许任何字符，但后面的字符可能会对管道名称进行一些处理，例如解析 .. 序列。尽管如此，管道空间是平面的。管道不会持续，当最后一次引用关闭时，管道就会被删除。不要忘了 JavaScript 字符串转义需要使用双反斜杠指定路径，例如：

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

net.Server 类#

查看英文版参与翻译

新增于: v0.1.90

这个类用于创建 TCP 或 IPC server。

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

查看英文版参与翻译

查看 net.createServer([options][, connectionListener]).

net.Server is an EventEmitter实现了以下事件:

'close' 事件#

查看英文版参与翻译

新增于: v0.5.0

当server关闭的时候触发. 注意,如果有连接存在, 直到所有的连接结束才会触发这个事件

'connection' 事件#

查看英文版参与翻译

新增于: v0.1.90

当一个新的connection建立的时候触发. socket 是一个 net.Socket的实例对象.

'error' 事件#

查看英文版参与翻译

新增于: v0.1.90

当错误出现的时候触发. 不同与 net.Socket, 'close' 事件不会在这个事件触发后继续触发 除非 server.close() 是手动调用. 在 server.listen()中的例子.

'listening' 事件#

查看英文版参与翻译

新增于: v0.1.90

当服务被绑定后调用 server.listen().

server.address()#

查看英文版参与翻译

新增于: v0.1.90

如果在IP socket上监听,则返回绑定的ip地址, 地址族和操作系统报告的服务端口 在找到操作系统分配的地址时，找到指定的端口是有用的.返回一个有 port, family, 和 address 属性: { port: 12346, family: 'IPv4', address: '127.0.0.1' }的对象

对于在管道或UNIX域套接字上侦听的server,该名称将返回为字符串

例子:

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());
});

只有到了 'listening' 事件被触发时候.才可以调用 server.address()

server.close([callback])#

查看英文版参与翻译

新增于: v0.1.90

停止 server接受建立新的connections并保持已经存在的connections.此功能是异步的,当所有的connections关闭同时server响应 'close'事件的时候,server将会最终关闭. 一旦'close'发生将会调用可选的回调函数. 与该事件不同, 如果服务器在关闭时未打开，则将使用错误作为唯一参数。

返回 server。

server.connections#

查看英文版参与翻译

新增于: v0.2.0废弃于: v0.9.7

稳定性: 0 - 废弃的: 使用 server.getConnections() 来替代。

服务器上并发的连接数。

当发送一个 socket 给用child_process.fork() 创建的子进程时，这会返回 null 。要轮询分叉（forks）获得活动连接数可以使用异步的server.getConnections()来替代。

server.getConnections(callback)#

查看英文版参与翻译

新增于: v0.9.7

异步获取服务器的当前并发连接数。当 socket 被传递给子进程时工作。

回调函数的两个参数是 err 和 count。

server.listen()#

查看英文版参与翻译

为 connections 启动一个 server 监听. 一个 net.Server 可以是一个 TCP 或者 一个 IPC server，这取决于它监听什么。

可能的参数:

这个函数是异步的。当 server 开始监听，'listening' 事件会触发。最后一个参数 callback 将会被添加为'listening' 事件的监听器。

所有的 listen() 方法可以传入一个 backlog 参数来指定待连接队列的最大长度。 实际长度将通过 OS 的 sysctl 设置， 例如 linux 里的 tcp_max_syn_backlog 和 somaxconn。 这个参数的默认值是511 (不是512）

说明：

  • 所有的 net.Socket 都被设置为 SO_REUSEADDR (详见 socket(7))

  • server.listen() 方法可能会被调用多次。每个后续的调用都将使用其提供的选项重新打开服务器。

监听时，其中一个最常见的错误是 EADDRINUSE。这是因为另一个 server 已经监听了该请求中的 port / path / handle。 处理这种情况的一种方法是在一定时间后重试：

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

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

查看英文版参与翻译

新增于: v0.5.10

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

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

注意：在Windows上不支持在文件描述符上进行监听。

server.listen(options[, callback])#

查看英文版参与翻译

新增于: v0.11.14

如果指定了 port 参数，该方法的行为跟 server.listen([port][, hostname][, backlog][, callback]) 一样。否则，如果指定了 path 参数，该方法的行为与 server.listen(path[, backlog][, callback]) 一致。如果没有 port 或者 path 参数，则会抛出一个错误。

如果 exclusive 是 false（默认），则集群的所有进程将使用相同的底层句柄，允许共享连接处理任务。如果 exclusive 是 true，则句柄不会被共享，如果尝试端口共享将导致错误。监听独立端口的例子如下。

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

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

查看英文版参与翻译

新增于: v0.1.90

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

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

查看英文版参与翻译

新增于: v0.1.90

启动一个TCP服务监听输入的port和host。

如果port省略或是0，系统会随意分配一个在'listening'事件触发后能被server.address().port检索的无用端口。

如果host省略，如果IPv6可用，服务器将会接收基于unspecified IPv6 address (::)的连接，否则接收基于unspecified IPv4 address (0.0.0.0)的连接

注意: 在大多数的系统, 监听unspecified IPv6 address (::)可能导致net.Server也监听unspecified IPv4 address (0.0.0.0).

server.listening#

查看英文版参与翻译

新增于: v5.7.0

一个布尔值， 表明 server 是否正在监听连接

server.maxConnections#

查看英文版参与翻译

新增于: v0.2.0

设置该属性使得当 server 连接数过多时拒绝连接。

一旦将一个 socket 发送给 child_process.fork() 生成的子进程，就不推荐使用该选项。

server.ref()#

查看英文版参与翻译

新增于: v0.9.1

与 unref 相反，在一个已经调用 unref 的 server 中调用 ref，如果 server 是仅存的 server，则程序不会退出（默认）。对一个已经调用 ref 的 server 再次调用 ref 将不会再有效果。

server.unref()#

查看英文版参与翻译

新增于: v0.9.1

如果这个server在事件系统中是唯一有效的，那么对server调用unref将允许程序退出。如果这个server已经调用过unref那么再次调用将不会再有效果。

net.Socket 类#

查看英文版参与翻译

新增于: v0.3.4

这个类是 TCP 或 UNIX Socket 的抽象（在Windows上使用命名管道，而UNIX使用域套接字）。一个net.Socket也是一个duplex stream，所以它能被读或写，并且它也是一个EventEmitter。

net.Socket可以被用户创建并直接与server通信。举个例子，它是通过net.createConnection()返回的，所以用户可以使用它来与server通信。

当一个连接被接收时，它也能被Node.js创建并传递给用户。比如，它是通过监听在一个net.Server上的'connection'事件触发而获得的，那么用户可以使用它来与客户端通信。

new net.Socket([options])#

查看英文版参与翻译

新增于: v0.3.4

创建一个 socket 对象。

  • options <Object> 可用选项有：   fd: <number> 如果指定了该参数，则使用一个给定的文件描述符包装一个已存在的 socket，否则将创建一个新的 socket。   allowHalfOpen <boolean> 指示是否允许半打开的 TCP 连接。详情查看 net.createServer() 和 'end' 事件。默认是 false。   readable <boolean> 当传递了 fd 时允许读取 socket，否则忽略。默认 false。   writable <boolean> 当传递了 fd 时允许写入 socket，否则忽略。默认 false。
  • Returns: <net.Socket>

新创建的 socket 可以是 TCP socket 也可以是 IPC 端点流，取决于它连接 connect() 到什么。

'close' 事件#

查看英文版参与翻译

新增于: v0.1.90
  • had_error <boolean> 如果 socket 有传输错误就为 true。

一旦 socket 完全关闭就发出该事件。参数 had_error 是 boolean 类型，表明 socket 被关闭是否取决于传输错误。

'connect' 事件#

查看英文版参与翻译

新增于: v0.1.90

当一个 socket 连接成功建立的时候触发该事件。 查看 net.createConnection()。

'data' 事件#

查看英文版参与翻译

新增于: v0.1.90

当接收到数据的时触发该事件。data 参数是一个 Buffer 或 String。数据编码由 socket.setEncoding() 设置。（在 Readable Stream 章节查看更多信息。）

注意当 Socket 发送 data 事件的时候，如果没有监听者数据将会丢失。

'drain' 事件#

查看英文版参与翻译

新增于: v0.1.90

当写入缓冲区变为空时触发。可以用来做上传节流。

也可以查看：socket.write() 的返回值

'end' 事件#

查看英文版参与翻译

新增于: v0.1.90

当 socket 的另一端发送一个 FIN 包的时候触发，从而结束 socket 的可读端。

默认情况下（allowHalfOpen为false），socket 将发送一个 FIN 数据包，并且一旦写出它的等待写入队列就销毁它的文件描述符。当然，如果 allowHalfOpen 为 true，socket 就不会自动结束 end() 它的写入端，允许用户写入任意数量的数据。用户必须调用 end() 显示地结束这个连接（例如发送一个 FIN 数据包。）

'error' 事件#

查看英文版参与翻译

新增于: v0.1.90

当错误发生时触发。'close' 事件也会紧接着该事件被触发。

'lookup' 事件#

查看英文版参与翻译

版本历史
Version变更
v5.10.0

The host parameter is supported now.

v0.11.3

新增于: v0.11.3

在找到主机之后创建连接之前触发。不可用于 UNIX socket。

Event: 'ready'#

查看英文版参与翻译

新增于: v9.11.0

Emitted when a socket is ready to be used.

Triggered immediately after 'connect'.

'timeout' 事件#

查看英文版参与翻译

新增于: v0.1.90

当 socket 超时的时候触发。该事件只是用来通知 socket 已经闲置。用户必须手动关闭。

也可以查看：socket.setTimeout()

socket.address()#

查看英文版参与翻译

新增于: v0.1.90

返回操作系统报告的 socket 的地址、地址族和端口。返回的对象有三个属性，例如： { port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.bufferSize#

查看英文版参与翻译

新增于: v0.3.8

net.Socket 具有该属性，socket.write() 工作时需要。它可以帮助用户快速启动和运行。计算机（处理速度）不能总是跟上 socket 的写入速度 - 网络连接可能太慢了。 Node.js 内部将维护一个写入 socket 的数据队列，并在可能的时候将数据发送出去。（内部实现是对 socket 的文件描述符进行轮训其是否是可写状态。）

使用内部缓冲的结果是可能造成内存的增长。此属性显示当前即将被写入的缓冲的字符数。（字符串的数目大致等于即将被写入的字节，但缓冲可能包含字符串，而字符串是惰性编码的，所以实际的字节数是不知道的。）

对处理大量或持续增长的 bufferSize 有经验的用户应该注意使用 socket.pause() and socket.resume() 对他们程序中的数据流进行节流。

socket.bytesRead#

查看英文版参与翻译

新增于: v0.5.3

接收的字节数量。

socket.bytesWritten#

查看英文版参与翻译

新增于: v0.5.3

发送的字节数量。

socket.connect()#

查看英文版参与翻译

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

可能的签名：

该方法是异步的。当连接建立了的时候，'connect' 事件将会被触发。如果连接过程中有问题，'error' 事件将会代替 'connect' 事件被触发，并将错误信息传递给 'error' 监听器。 最后一个参数 connectListener，如果指定了，将会被添加为 'connect' 事件的。

socket.connect(options[, connectListener])#

查看英文版参与翻译

版本历史
Version变更
v6.0.0

The hints option defaults to 0 in all cases now. Previously, in the absence of the family option it would default to dns.ADDRCONFIG | dns.V4MAPPED.

v5.11.0

The hints option is supported now.

v0.1.90

新增于: v0.1.90

在给定的 socket 上初始化一个连接。通常该方法是不需要的，应该使用 net.createConnection() 来创建和打开 socket。一般只在实现一个自定义的 Socket 的时候使用该方法。

对于 TCP 连接可能的 options 有：

对于 IPC 连接可能的 options 有：

返回 socket.

socket.connect(path[, connectListener])#

查看英文版参与翻译

在给定的 socket 上初始化 IPC 。

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

返回 socket。

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

查看英文版参与翻译

新增于: v0.1.90

在给定的 socket 上初始化一个 TCP 连接。

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

返回 socket。

socket.connecting#

查看英文版参与翻译

新增于: v6.1.0

如果为 true 则socket.connect(options[, connectListener]) 被调用但还未结束。当发送 connect 事件或调用 socket.connect(options[, connectListener]) 的回调函数的时候会被设置为 false。

socket.destroy([exception])#

查看英文版参与翻译

新增于: v0.1.90

确保在该 socket 上不再有 I/O 活动。仅在出现错误的时候才需要（如解析错误等）。

如果制定了 exception，则将会触发一个 'error' 事件，任何监听器都将接收到 exception 作为一个参数。

socket.destroyed#

查看英文版参与翻译

一个布尔值，用来指示连接是否已经被销毁。一旦连接被销毁就不能再使用它传输任何数据。

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

查看英文版参与翻译

新增于: v0.1.90

半关闭 socket。例如发送一个 FIN 包。服务端仍可以发送数据。

如果指定了 data，则相当于调用 socket.write(data, encoding) 之后再调用 socket.end()。

socket.localAddress#

查看英文版参与翻译

新增于: v0.9.6

远程客户端连接的本地 IP 地址字符串。例如，一个服务端正在连接到 '0.0.0.0'，客户端连接到的是 '192.168.1.1'，则 socket.localAddress 的值是 '192.168.1.1'。

socket.localPort#

查看英文版参与翻译

新增于: v0.9.6

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

socket.pause()#

查看英文版参与翻译

暂停读写数据。也就是说，'data' 将不会再被触发。可以用于上传节流。

socket.ref()#

查看英文版参与翻译

新增于: v0.9.1

与 unref 相反，在一个已经调用 unref 的 socket 中调用 ref，如果 socket 是仅存的 socket，则程序不会退出（默认）。对一个已经调用 ref 的 socket 再次调用 ref 将不会再有效果。

socket.remoteAddress#

查看英文版参与翻译

新增于: v0.5.10

用字符串表示的远程 IP 地址。例如 '74.125.127.100' 或 '2001:4860:a005::68'。如果 socket 被销毁了（如客户端已经失去连接）则其值为 undefined。

socket.remoteFamily#

查看英文版参与翻译

新增于: v0.11.14

用字符串表示的远程 IP 协议族。'IPv4' 或 'IPv6'。

socket.remotePort#

查看英文版参与翻译

新增于: v0.5.10

用数字表示的远程端口。例如 80 或 21。

socket.resume()#

查看英文版参与翻译

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

socket.setEncoding([encoding])#

查看英文版参与翻译

新增于: v0.1.90

设置作为可读流（Readable Stream）的编码。在 stream.setEncoding() 查看更多详情。

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

查看英文版参与翻译

新增于: v0.1.92

启用/禁用长连接功能， 并且在第一个长连接探针被发送到一个空闲的 socket 之前可选则配置初始延迟。enable 默认为 false。

initialDelay（毫秒）用来设置接收到最后一个数据包和发送第一个长连接探针之间的延迟。将 initialDelay 设置为 0，则会保持默认值（或之前设置的值）不变。默认是 0。

socket.setNoDelay([noDelay])#

查看英文版参与翻译

新增于: v0.1.90

禁止 Nagle 。默认情况下 TCP 连接使用 Nagle 算法，在发送之前缓冲数据。将 noDelay 设置为 true 将会在每次 socket.write() 被调用的时候立即发送数据。noDelay默认是 true。

socket.setTimeout(timeout[, callback])#

查看英文版参与翻译

新增于: v0.1.90

当 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.unref()#

查看英文版参与翻译

新增于: v0.9.1

如果活跃的 socket 是事件系统中仅存的 socket，则调用 unref 将会允许程序退出。对一个已经调用了 unref 的 socket 再调用 unref 无效。

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

查看英文版参与翻译

新增于: v0.1.90

在 socket 上发送数据。第二个参数制定了字符串的编码 - 默认是 UTF8 编码。

如果全部数据都成功刷新到内核的缓冲则返回 true。如果全部或部分数据在用户内中排队，则返回 false。当缓冲再次空闲的时候将触发 'drain' 事件。

当数据最终都被写出之后，可选的 callback 参数将会被执行 - 可能不会立即执行。

net.connect()#

查看英文版参与翻译

net.createConnection() 的别名。

可能的签名：

net.connect(options[, connectListener])#

查看英文版参与翻译

新增于: v0.7.0

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

net.connect(path[, connectListener])#

查看英文版参与翻译

新增于: v0.1.90

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

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

查看英文版参与翻译

新增于: v0.1.90

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

net.createConnection()#

查看英文版参与翻译

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

当连接建立之后，在返回的 socket 上将触发一个 'connect' 事件。若制定了最后一个参数 connectListener，则它将会被添加到 'connect' 事件作为一个监听器。

可能的签名有：

注意: The net.connect() 函数也是该函数的别名。

net.createConnection(options[, connectListener])#

查看英文版参与翻译

新增于: v0.1.90

可选的选项，查看 new net.Socket([options]) 和 socket.connect(options[, connectListener])。

附加的选项：

下面是在 net.createServer() 章节描述的 server 的客户端示例：

const net = require('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');
});

如果要连接到 /tmp/echo.sock，第二行只需要改为：

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

net.createConnection(path[, connectListener])#

查看英文版参与翻译

新增于: v0.1.90

初始化一个 IPC 连接。

该方法使用所有默认选项创建一个新的 net.Socket，使用 socket.connect(path[, connectListener]) 立即初始化连接，然后返回初始化连接的 net.Socket。

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

查看英文版参与翻译

新增于: v0.1.90

初始化一个TCP连接

这个函数用默认配置创建一个新的net.Socket，然后socket.connect(port[, host][, connectListener])初始化一个连接，并返回开启连接的那个 net.Socket。

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

查看英文版参与翻译

新增于: v0.5.0

Creates a new TCP or IPC server. 创建一个新的TCP或IPC服务。

  • options <Object>   allowHalfOpen <boolean> 表示是否允许一个半开的TCP连接。 默认值: false   pauseOnConnect <boolean> 一旦来了连接，是否暂停套接字。 默认值: false
  • connectionListener <Function> 为'connection' 事件自动设置一个监听器。
  • 返回: <net.Server>

如果 allowHalfOpen 被设置为true, 那么当socket.end() 被显式调用时, 如果对边套接字发送了一个FIN包，服务只会返回一个FIN数据包， 这会持续到后来连接处在半闭状态 (不可读但是可写)。 请查看'end' 事件和 RFC 1122 (4.2.2.13节) 获取更多信息。

如果 pauseOnConnect 被设置为 true, 那么与连接相关的套接字都会暂停，也不会从套接字句柄读取数据。 这样就允许连接在进程之间传递，避免数据被最初的进程读取。 如果想从一个暂停的套接字开始读数据，请调用socket.resume()

服务可以是一个TCP服务或者一个 IPC 服务, 这取决于listen() 监听什么

这是一个简单的TCP回声服务器在8124端口上监听连接的例子：

const net = require('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');
});

用 telnet测试:

$ telnet localhost 8124

想监听 /tmp/echo.sock 只需改最后三行为：

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

用 nc 连一个 UNIX 域套接字服务器:

$ nc -U /tmp/echo.sock

net.isIP(input)#

查看英文版参与翻译

新增于: v0.3.0

测试 input 是否是 IP 地址。无效的字符串则返回 0，IPv4 地址则返回 4，IPv6的地址则返回 6。

net.isIPv4(input)#

查看英文版参与翻译

新增于: v0.3.0

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

net.isIPv6(input)#

查看英文版参与翻译

新增于: v0.3.0

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