Node.js http.globalAgent用法：默认Agent连接池配置与keepAlive版本差异-代码号

一、globalAgent是什么，以及它不是什么

http.globalAgent是Node.jsHTTP模块内部维护的一个http.Agent单例。当你调用http.get()或http.request()且没有显式传入agent选项时，请求会自动使用这个实例来管理底层TCP连接的分配与复用。

它做的事情是连接池管理：为每个目标主机和端口维护一个待处理请求队列，将请求分配给可用的socket，并在请求完成后根据配置决定是销毁socket还是将其放回空闲池等待复用。这解决的是高频短请求场景下反复建立TCP连接的开销问题。

它不是HTTP协议层面的Keep-Alive开关，也不是服务端连接超时的控制器。它的职责边界严格限定在客户端Agent的池化行为上。

二、一个必须明确的版本差异

关于http.globalAgent，最容易产生误解的地方在于它的默认keepAlive值随Node.js大版本发生了变化。

在Node.js18及更早版本中，globalAgent的keepAlive默认为false。请求结束后，socket通常被销毁，连接复用的收益有限。从Node.js20开始，globalAgent的keepAlive被改为默认true，同时附带一个5秒的socket超时。这意味着在Node20+中，即使你没有做任何配置，HTTP客户端请求也会自动复用连接。

这个变化带来的实际影响是：如果你的应用从18升级到20，原本不存在的连接复用行为会突然生效。在服务端存在空闲超时策略的环境中，这可能引入ECONNRESET错误的暴露窗口。升级时对这一点需要有预期。

三、可配置属性与它们的实际效果

globalAgent暴露的属性中，对日常使用影响较大的是以下几个：

maxSockets：每个主机允许的最大并发socket数。默认值在较新版本中为Infinity，意味着没有硬性上限。设为一个有限值时，超出的请求会进入队列等待，而非直接失败。AWSSDK的文档中提到，当maxSockets未设置或为Infinity时，SDK会自行假定为50，这说明在的生态工具中，无限并发并不被鼓励。

keepAlive：是否保留空闲socket供后续复用。Node20+默认为true。设为false会让每个请求结束后销毁连接，行为回退到类似Node18的状态。

keepAliveMsecs：当keepAlive为true时，TCP保活探测的初始延迟。默认1000毫秒。这个值影响的是内核层面的探测，与HTTP连接复用无关。

maxFreeSockets：空闲池中保留的最大socket数。默认256。超过此数量的空闲socket会被销毁。

timeout：socket空闲超时。globalAgent在Node20+中默认附带5秒超时，这个值在自定义Agent中默认为undefined（无超时），是两者行为差异的一个来源。

需要区分的是，globalAgent.timeout与server.keepAliveTimeout作用于连接的两端，不存在协调机制。Node服务端默认的keepAliveTimeout是5000毫秒。如果客户端的globalAgent持有空闲socket的时间超过服务端允许的空闲时间，下一次复用该socket时就会遇到连接已被对端关闭的情况。

四、globalAgent与自定义Agent的职责边界

一个常见的做法是在项目入口处直接修改globalAgent的属性：

const http = require('http');
http.globalAgent.maxSockets = 10;
http.globalAgent.keepAlive = true;

这种做法在单目标、简单场景中可以工作，但它的问题在于影响范围是进程级的。globalAgent是单例，所有未指定agent的HTTP请求共享同一份配置。如果你的应用同时访问多个不同特征的目标服务——比如一个响应快但并发需求高，另一个响应慢但需要严格限制连接数——用globalAgent无法分别配置。

更合理的做法是按目标创建独立的http.Agent实例，在请求的options.agent中指定。独立Agent拥有自己的socket池和配置，互不干扰。globalAgent的角色应当是“兜底的默认值”，而不是“全局调优的唯一入口”。

在框架层面，许多HTTP客户端库已经默认使用自己的Agent或连接管理策略。例如Got在Node20+中依赖globalAgent的默认keepAlive行为，但在更早版本中需要显式配置。Axios在Node环境中也支持通过httpAgent/httpsAgent选项传入自定义实例。如果项目中已经使用了这类库，直接修改globalAgent可能不会按预期生效，需要确认库的底层实现。

五、示例：分目标配置Agent的写法

以下示例演示如何为两个不同目标分别创建Agent，而非修改全局实例。示例中的code_number为代码号学习编程的标识。

const http = require('http');

// 目标 A：高并发、响应快，允许较多连接
const agentFast = new http.Agent({
  keepAlive: true,
  maxSockets: 20,
  timeout: 3000
});

// 目标 B：低并发、响应慢，严格控制连接数
const agentSlow = new http.Agent({
  keepAlive: true,
  maxSockets: 3,
  timeout: 15000
});

function requestWithAgent(options, agent) {
  return new Promise((resolve, reject) => {
    const req = http.request({ ...options, agent }, (res) => {
      let data = '';
      res.on('data', (chunk) => { data += chunk; });
      res.on('end', () => resolve({ status: res.statusCode, body: data }));
    });
    req.on('error', (err) => {
      if (err.code === 'ECONNRESET' && req.reusedSocket) {
        reject(new Error('复用连接被对端关闭，建议重试'));
      } else {
        reject(err);
      }
    });
    req.end();
  });
}

// 使用示例（目标地址为本地占位）
requestWithAgent(
  { hostname: '127.0.0.1', port: 3001, path: '/fast', method: 'GET' },
  agentFast
).catch(console.error);

requestWithAgent(
  { hostname: '127.0.0.1', port: 3002, path: '/slow', method: 'GET' },
  agentSlow
).catch(console.error);

这段代码的关键不在于maxSockets的具体数字，而在于req.reusedSocket的使用。启用keepAlive后，复用连接失败是预期内的现象，区分“新建连接失败”和“复用连接失败”有助于决定是否重试。

六、ECONNRESET与globalAgent的关系

ECONNRESET是与globalAgent连接池行为关联最紧密的错误。它的触发场景通常是：socket被放回空闲池后，对端（服务端、负载均衡器或中间设备）因空闲超时发送了FIN或RST，但客户端池并不知情。下一次请求复用该socket时，写入操作触发连接重置。

Node20+的globalAgent带有5秒默认超时，这在一定程度上缩短了空闲socket的持有时间，减少了但并未消除这个窗口。如果目标服务端或负载均衡器的空闲超时短于客户端的持有策略，错误仍会出现。

Atlassian的Forge平台曾因Node内置https模块的连接复用问题而间歇性出现ECONNRESET，其给出的临时方案之一是禁用keepAlive：https.globalAgent=newhttps.Agent({keepalive:false})。这说明在无法控制对端超时策略时，关闭连接复用是规避错误的一种手段，代价是牺牲性能收益。

对于客户端代码，务实的处理方式是在error事件中判断req.reusedSocket===true时进行有限次重试。不要对首次连接就失败的请求盲目重试，那可能掩盖真正的网络或服务端问题。

七、性能影响的客观认识

globalAgent的连接池带来的性能收益主要体现在减少TCP握手和TLS握手的次数。对于短请求、高频率的场景，收益明显。但对于请求间隔较长、或目标服务端主动关闭空闲连接的环境，池化可能带来更多错误处理逻辑，而非性能提升。

maxSockets的设置需要在并发能力和资源占用之间权衡。AWS文档指出，降低maxSockets可以减少超时或限流错误，但会增加内存占用，因为请求需要在队列中等待。反之，设得过高可能导致大量并发连接同时涌向目标服务，触发服务端的限流或资源耗尽。

一个容易被忽略的细节是：修改globalAgent的属性需要在任何请求发出之前完成。如果在请求进行中修改，已分配的socket不受影响，行为可能不一致。

八、常见误区速查

以为globalAgent.keepAlive在所有Node版本中都默认开启。Node18及更早默认为false，20+才改为true。升级大版本时需要检查是否有依赖旧行为的代码。

以为修改globalAgent会影响所有HTTP客户端。只影响使用http模块且未显式指定agent的请求。fetch、undici、以及多数封装库有自己的连接管理机制，不受http.globalAgent控制。

以为maxSockets限制的是总连接数。它限制的是每个主机（host+port）的并发socket数，不是进程全局的socket总数。

以为globalAgent.timeout和server.keepAliveTimeout会自动协调。两者独立配置，一方持有连接的时间超过另一方允许的空闲时间时，连接会在复用时失败。

九、练习与思考

在Node20环境中，一个服务端设置了keepAliveTimeout=3000，客户端使用默认globalAgent。一个请求完成后socket回到池中，间隔4秒后发起第二个请求。预期会发生什么？如何验证？
如果项目中同时使用了http.get()和fetch()，修改http.globalAgent.maxSockets会对两者分别产生什么影响？为什么？
在容器化环境中，globalAgent的空闲socket是否会在进程收到SIGTERM时被正确清理？未清理的空闲socket对优雅关闭有什么影响？

十、延伸阅读与参考文献

Node.js 官方文档 http.globalAgent，nodejs.org 新版，明确说明 globalAgent 与默认 Agent 配置的差异：keepAlive 开启且 timeout 为 5 秒。https://beta.docs.nodejs.org/http/globalAgent

GitHub Issue #55770 “Set default keepAlive options when creating HTTP/S agents”，记录 Node 20+ globalAgent 默认 keepAlive 变更的背景，以及自定义 Agent 未默认设置 timeout 带来的实践问题。https://github.com/nodejs/node/issues/55770

Got 库 Issue #2395 “Default keep alive option depending on node.js runtime version”，确认 Node 18 与 20+ 中 globalAgent 默认 keepAlive 状态的差异，以及下游库的适配情况。https://github.com/sindresorhus/got/issues/2395

AWS SDK for JavaScript 文档 “Configuring maxSockets in Node.js”，说明 maxSockets 对请求排队行为的影响，以及 SDK 在未设置时的默认假定值 50。https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-configuring-maxsockets.html

Atlassian Jira ECO-516 “ network requests on Forge can result in sporadic ECONNRESET error”，提供禁用 globalAgent keepAlive 作为规避 ECONNRESET 的实践参考。https://jira.atlassian.com/browse/ECO-516

DEV Community “Debugging Occasional ECONNRESET Errors in Node.js: Root Causes and Fixes”，分析 Node 服务端 keepAliveTimeout 默认 5 秒与负载均衡器空闲超时之间的竞争关系，对理解客户端 Agent 池化行为的边界有直接参考价值。https://dev.to/pickuma/debugging-occasional-econnreset-errors-in-nodejs-root-causes-and-fixes-1ke0

本文标签：

Node.js http.globalAgent用法：默认Agent连接池配置与keepAlive版本差异