new Agent([options])


  • options <Object> 要在代理上设置的可配置选项集。 可以有以下字段:
    • keepAlive <boolean> 即使没有未完成的请求,也要保留套接字,这样它们就可以用于未来的请求,而无需重新建立 TCP 连接。 不要与 Connection 标头的 keep-alive 值混淆。 使用代理时总是发送 Connection: keep-alive 标头,除非显式指定了 Connection 标头或当 keepAlivemaxSockets 选项分别设置为 falseInfinity,在这种情况下将使用 Connection: close默认值: false
    • keepAliveMsecs <number> 使用 keepAlive 选项时,指定 TCP Keep-Alive 数据包的初始延迟。 当 keepAlive 选项为 falseundefined 时则忽略。 默认值: 1000
    • maxSockets <number> 每个主机允许的最大套接字数量。 如果同一主机打开多个并发连接,则每个请求都将使用新的套接字,直到达到 maxSockets 值。 如果主机尝试打开的连接数超过 maxSockets,则额外的请求将进入待处理请求队列,并在现有连接终止时进入活动连接状态。 这确保在任何时间点,给定的主机最多有 maxSockets 个活动连接。 默认值: Infinity
    • maxTotalSockets <number> 所有主机总共允许的最大套接字数量。 每个请求将使用新的套接字,直到达到最大值。 默认值: Infinity
    • maxFreeSockets <number> 每台主机在空闲状态下保持打开的最大套接字数。 仅当 keepAlive 设置为 true 时才相关。 默认值: 256
    • scheduling <string> 选择下一个要使用的空闲套接字时应用的调度策略。 它可以是 'fifo''lifo'。 两种调度策略的主要区别在于 'lifo' 选择最近使用的套接字,而 'fifo' 选择最近最少使用的套接字。 在每秒请求率较低的情况下,'lifo' 调度将降低选择可能因不活动而被服务器关闭的套接字的风险。 在每秒请求率较高的情况下,'fifo' 调度将最大化打开套接字的数量,而 'lifo' 调度将保持尽可能低。 默认值: 'lifo'
    • timeout <number> 套接字超时(以毫秒为单位)。 这将在创建套接字时设置超时。

socket.connect() 中的 options 也受支持。

http.request() 使用的默认 http.globalAgent 将所有这些值设置为各自的默认值。

要配置其中任何一个,则必须创建自定义的 http.Agent 实例。

const http = require('node:http');
const keepAliveAgent = new http.Agent({ keepAlive: true });
options.agent = keepAliveAgent;
http.request(options, onResponseCallback);
  • options <Object> Set of configurable options to set on the agent. Can have the following fields:
    • keepAlive <boolean> Keep sockets around even when there are no outstanding requests, so they can be used for future requests without having to reestablish a TCP connection. Not to be confused with the keep-alive value of the Connection header. The Connection: keep-alive header is always sent when using an agent except when the Connection header is explicitly specified or when the keepAlive and maxSockets options are respectively set to false and Infinity, in which case Connection: close will be used. Default: false.
    • keepAliveMsecs <number> When using the keepAlive option, specifies the initial delay for TCP Keep-Alive packets. Ignored when the keepAlive option is false or undefined. Default: 1000.
    • maxSockets <number> Maximum number of sockets to allow per host. If the same host opens multiple concurrent connections, each request will use new socket until the maxSockets value is reached. If the host attempts to open more connections than maxSockets, the additional requests will enter into a pending request queue, and will enter active connection state when an existing connection terminates. This makes sure there are at most maxSockets active connections at any point in time, from a given host. Default: Infinity.
    • maxTotalSockets <number> Maximum number of sockets allowed for all hosts in total. Each request will use a new socket until the maximum is reached. Default: Infinity.
    • maxFreeSockets <number> Maximum number of sockets per host to leave open in a free state. Only relevant if keepAlive is set to true. Default: 256.
    • scheduling <string> Scheduling strategy to apply when picking the next free socket to use. It can be 'fifo' or 'lifo'. The main difference between the two scheduling strategies is that 'lifo' selects the most recently used socket, while 'fifo' selects the least recently used socket. In case of a low rate of request per second, the 'lifo' scheduling will lower the risk of picking a socket that might have been closed by the server due to inactivity. In case of a high rate of request per second, the 'fifo' scheduling will maximize the number of open sockets, while the 'lifo' scheduling will keep it as low as possible. Default: 'lifo'.
    • timeout <number> Socket timeout in milliseconds. This will set the timeout when the socket is created.

options in socket.connect() are also supported.

The default http.globalAgent that is used by http.request() has all of these values set to their respective defaults.

To configure any of them, a custom http.Agent instance must be created.

const http = require('node:http');
const keepAliveAgent = new http.Agent({ keepAlive: true });
options.agent = keepAliveAgent;
http.request(options, onResponseCallback);