前言

我們有了以下知識

• EventEmitter
• stream-overview
• stream.Writable 生命週期
• stream.Writable 記憶體管理、效能優化、錯誤處理
• stream.Readable 生命週期
• stream.Readable 錯誤處理與比較解析
• stream objectMode 與 pipe 實戰教學
• Node.js net.Socket 教學：TCP 連線應用
• Node.js TCP Client Socket 生命週期：lookup、connect 事件
• 深入 net.Socket：4-way handshake、socket.end vs destroy 差異

終於可以進到 Node.js http 模組了！

本文測試、引用的 Node.js 原始碼為 v24.x

Why http.Agent ?

如果沒有 http.Agent 的話

import http from "http";

// server
const server = http.createServer((req, res) => {
  console.log("req.headers", req.headers);
  res.end();
});
server.listen(5000);

// client
const noop = () => {};
const request = http.request({
  host: "localhost",
  port: 5000,
  path: "/",
  agent: false, // ✅ 不使用 `http.Agent`
});
request.end();
request.on("response", (res) => {
  console.log("res.headers", res.headers);
  res.resume();
  res.on("end", noop);
});

從 log 的 Connection: close 可以得出結論：每次 HTTP round trip 結束，都會關閉 TCP 連線

req.headers { host: 'localhost:5000', connection: 'close' }
res.headers {
  date: 'Fri, 06 Feb 2026 01:33:20 GMT',
  connection: 'close',
  'content-length': '0'
}

從 TCP 的視角來看，每次都需要
"三次交握開啟連線" + "四次交握關閉連線"，效能上會比較差

http.Agent 為此而生，它幫使用者管理

• TCP socket 連線池
• concurrent 連線上限

new http.Agent(options)

https://nodejs.org/docs/latest-v24.x/api/http.html#new-agentoptions

methods

properties

這三個是在 new http.Agent(options) 設定的，故不多贅述

• maxSockets
• maxFreeSockets
• maxTotalSockets

Read-Only properties

這三個則是由 http.Agent 控制的

• freeSockets：連線池，可使用的 sockets

{
  'example.com:80:': [Socket, Socket],
  'www.google.com:80:': [Socket, Socket]
}

• requests：pending requests queue。超過 options.maxSockets 或是 options.maxTotalSockets 的 requests 就會被丟到這裡

{
  'example.com:80:': [ClientRequest, ClientRequest],
  'www.google.com:80:': [ClientRequest, ClientRequest]
}

• sockets：http.Agent 使用中的 sockets

{
  'example.com:80:': [Socket, Socket],
  'www.google.com:80:': [Socket, Socket]
}

這邊的 example.com:80: 跟 www.google.com:80: 就是 agent.getName([options]) 回傳的 group key

options.maxSockets 圖解

ClientRequest 跟 net.Socket 連結的橋樑

當你用 http.request 發起請求時，背後會優先從 http.Agent 的連線池（freeSockets）挑選一個已連線的 net.Socket 關聯到這個 ClientRequest。若 freeSockets 為空，就會建立一個新的 TCP 連線

詳細的實作可以看 lib/_http_agent.js 的 Agent.prototype.addRequest

我們寫個 PoC 來測試

import http from "http";
import assert from "assert";
import { nextTick } from "process";

// HTTP server
const httpServer = http.createServer((req, res) => res.end());
httpServer.listen(5000);

// HTTP client
const agent = new http.Agent({ keepAlive: true });
// ✅ 剛開始沒有建立任何 TCP 連線
assert(Object.keys(agent.freeSockets).length === 0);
const clientRequest1 = http.request({ host: "localhost", port: 5000, agent });
clientRequest1.on("socket", () => console.log(clientRequest1.reusedSocket)); // ❌ false
clientRequest1.end();
clientRequest1.on("close", () =>
  nextTick(() => {
    // ✅ 使用 nextTick，確保 localhost:5000 的 TCP socket 已經回收到 freeSockets
    assert(Object.keys(agent.freeSockets).length === 1);
    const clientRequest2 = http.request({
      host: "localhost",
      port: 5000,
      agent,
    });
    clientRequest2.on("socket", () => console.log(clientRequest2.reusedSocket)); // ✅ true
    clientRequest2.end();
  }),
);

• request.on("socket")：ClientRequest 跟 net.Socket 關聯的瞬間觸發
• request.reusedSocket：該 net.Socket 是否關聯過其他 ClientRequest

小結