HTTP

稳定性：2 - 稳定

此模块包含客户端和服务器，可通过 require('node:http') (CommonJS) 或 import * as http from 'node:http' (ES 模块) 导入。

Node.js 中的 HTTP 接口旨在支持该协议的许多传统上难以使用的功能。 特别是大型的、可能分块编码的消息。该接口谨慎地从不缓冲整个请求或响应，以便 用户能够流式传输数据。

HTTP 消息头由如下对象表示：

{ "content-length": "123",
  "content-type": "text/plain",
  "connection": "keep-alive",
  "host": "example.com",
  "accept": "*/*" }

键为小写。值不会被修改。

为了支持各种可能的 HTTP 应用，Node.js HTTP API 非常底层。它仅处理流处理和消息 解析。它将消息解析为头和主体，但不 解析实际的头或主体。

详见 message.headers 了解如何处理重复头的详情。

接收到的原始头信息保留在 rawHeaders 属性中，它是一个 [key, value, key2, value2, ...] 数组。例如， 前面的消息头对象可能具有如下 rawHeaders 列表：

[ "ConTent-Length", "123456",
  "content-LENGTH", "123",
  "content-type", "text/plain",
  "CONNECTION", "keep-alive",
  "Host", "example.com",
  "accepT", "*/*" ]

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

在复用的 HTTP/1.1 keep-alive 连接上，响应会按照该连接上的请求顺序与请求关联。HTTP/1.1 keep-alive 除了这种顺序之外，不提供按请求的响应归属。需要为每个请求隔离连接的应用程序可以使用单独的 Agent，禁用 keep-alive，或传入 agent: false。

当连接被客户端或服务器关闭时，它会从连接池中移除。连接池中的任何未使用套接字都会被取消引用（unref），以便在没有未完成请求时不会让 Node.js 进程继续运行。（参见 socket.unref()）。

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

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

使用 agent: false 可避免某个请求复用连接。

new Agent(options?): void

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

要配置其中任何一项，必须创建自定义 http.Agent 实例。

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

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

agent.createConnection(options, callback?): void

创建一个用于 HTTP 请求的套接字/流。

默认情况下，此函数的行为与 net.createConnection() 完全相同， 会同步返回创建的套接字。签名中的可选 callback 参数不会由此默认实现使用。

但是，自定义 agent 可以重写此方法以提供更大的灵活性， 例如异步创建套接字。重写 createConnection 时：

1. 同步创建套接字：重写的方法可以直接返回 套接字/流。
2. 异步创建套接字：重写的方法可以接受 callback， 并将创建的套接字/流传递给它（例如，callback(null, newSocket)）。 如果在创建套接字期间发生错误，应将其作为第一个 参数传递给 callback（例如，callback(err)）。

agent 将使用 options 和此内部 callback 调用所提供的 createConnection 函数。 agent 提供的 callback 签名为 (err, stream)。

agent.keepSocketAlive(socket): void

当 socket 从请求中分离并可由 Agent 持久化时调用。默认行为是：

socket.setKeepAlive(true, this.keepAliveMsecs);
socket.unref();
return true;

此方法可被特定的 Agent 子类重写。如果此 方法返回假值，套接字将被销毁，而不是被持久化 以供下一个请求使用。

socket 参数可以是 net.Socket 的实例，即 stream.Duplex 的子类。

agent.reuseSocket(socket, request): void

当 socket 因 keep-alive 选项而被持久化后附加到 request 时调用。 默认行为是：

socket.ref();

此方法可被特定的 Agent 子类重写。

socket 参数可以是 net.Socket 的实例，即 stream.Duplex 的子类。

agent.destroy(): void

销毁 agent 当前使用的任何套接字。

通常不需要这样做。但是，如果使用启用了 keepAlive 的 agent，则最好在不再需要时显式关闭 agent。否则， 套接字可能会在服务器终止它们之前保持打开很长时间。

• 类型：Object

当 keepAlive 启用时，包含 agent 当前等待使用的套接字数组的对象。 请勿修改。

freeSockets 列表中的套接字将在 'timeout' 时自动销毁并 从数组中移除。

agent.getName(options?): void

获取一组请求选项的唯一名称，以确定连接 是否可以复用。对于 HTTP agent，这将返回 host:port:localAddress 或 host:port:localAddress:family。对于 HTTPS agent， 名称包括 CA、cert、ciphers 和其他决定套接字可复用性的 HTTPS/TLS 特定选项。

• 类型: number

默认值为 256。对于启用了 keepAlive 的 agent，此值设置将保持处于空闲状态的套接字最大数量。

• 类型：number

默认设置为 Infinity。确定 agent 每个源可以打开多少个并发套接字。源是 agent.getName() 的返回值。

• 类型：number

默认设置为 Infinity。确定代理可以打开多少个并发套接字。与 maxSockets 不同，此参数适用于所有源。

• 类型：Object

包含尚未分配给 套接字的请求队列的对象。请勿修改。

• 类型：Object

包含 agent 当前使用的套接字数组的对象。 请勿修改。

• 继承：http.OutgoingMessage

此对象在内部创建并从 http.request() 返回。它表示一个_进行中_的请求，其头部已入队。头部仍然可以使用 setHeader(name, value)、getHeader(name)、removeHeader(name) API 进行可变操作。实际头部将随第一个数据块一起发送，或在调用 request.end() 时发送。

要获取响应，请为请求对象添加 'response' 监听器。当收到响应头部时，'response' 将从请求对象触发。'response' 事件执行时带有一个参数，该参数是 http.IncomingMessage 的实例。

在 'response' 事件期间，可以向响应对象添加监听器；特别是监听 'data' 事件。

如果没有添加 'response' 处理程序，则响应将被完全丢弃。但是，如果添加了 'response' 事件处理程序，则必须消费来自响应对象的数据，要么在有 'readable' 事件时调用 response.read()，要么添加 'data' 处理程序，要么调用 .resume() 方法。在数据被消费之前，'end' 事件不会触发。此外，在数据被读取之前，它将消耗内存，最终可能导致“进程内存溢出”错误。

为了向后兼容，只有在注册了 'error' 监听器的情况下，res 才会触发 'error'。

设置 Content-Length 头部以限制响应体大小。如果 response.strictContentLength 设置为 true，Content-Length 头部值不匹配将导致抛出 Error，标识为 code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'。

Content-Length 值应为字节数，而非字符数。使用 Buffer.byteLength() 来确定主体的字节长度。

稳定性：0 - 已废弃。请改为监听 'close' 事件。

当请求被客户端中止时触发。此事件仅在第一次调用 abort() 时触发。

表示请求已完成，或其底层连接在响应完成之前被提前终止。

每当服务器响应带有 CONNECT 方法的请求时触发。如果没有监听此事件，接收 CONNECT 方法的客户端的连接将被关闭。

除非用户指定了 net.Socket 以外的 socket 类型，否则保证此事件会传递一个 net.Socket 类的实例，它是 stream.Duplex 的子类。

演示如何监听 'connect' 事件的客户端和服务器配对示例：

import { createServer, request } from 'node:http';
import { connect } from 'node:net';
import { URL } from 'node:url';

// 创建一个 HTTP 隧道代理
const proxy = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // 连接到源服务器
  const { port, hostname } = new URL(`http://${req.url}`);
  const serverSocket = connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n');
    serverSocket.write(head);
    serverSocket.pipe(clientSocket);
    clientSocket.pipe(serverSocket);
  });
});

// 现在代理正在运行
proxy.listen(1337, '127.0.0.1', () => {

  // 向隧道代理发出请求
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  };

  const req = request(options);
  req.end();

  req.on('connect', (res, socket, head) => {
    console.log('已连接！');

    // 通过 HTTP 隧道发出请求
    socket.write('GET / HTTP/1.1\r\n' +
                 'Host: www.google.com:80\r\n' +
                 'Connection: close\r\n' +
                 '\r\n');
    socket.on('data', (chunk) => {
      console.log(chunk.toString());
    });
    socket.on('end', () => {
      proxy.close();
    });
  });
});

const http = require('node:http');
const net = require('node:net');
const { URL } = require('node:url');

// 创建一个 HTTP 隧道代理
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // 连接到源服务器
  const { port, hostname } = new URL(`http://${req.url}`);
  const serverSocket = net.connect(port || 80, hostname, () => {
    clientSocket.write('HTTP/1.1 200 Connection Established\r\n' +
                    'Proxy-agent: Node.js-Proxy\r\n' +
                    '\r\n');
    serverSocket.write(head);
    serverSocket.pipe(clientSocket);
    clientSocket.pipe(serverSocket);
  });
});

// 现在代理正在运行
proxy.listen(1337, '127.0.0.1', () => {

  // 向隧道代理发出请求
  const options = {
    port: 1337,
    host: '127.0.0.1',
    method: 'CONNECT',
    path: 'www.google.com:80',
  };

  const req = http.request(options);
  req.end();

  req.on('connect', (res, socket, head) => {
    console.log('已连接！');

    // 通过 HTTP 隧道发出请求
    socket.write('GET / HTTP/1.1\r\n' +
                 'Host: www.google.com:80\r\n' +
                 'Connection: close\r\n' +
                 '\r\n');
    socket.on('data', (chunk) => {
      console.log(chunk.toString());
    });
    socket.on('end', () => {
      proxy.close();
    });
  });
});

当服务器发送 “100 Continue” HTTP 响应时触发，通常是因为请求包含 “Expect: 100-continue”。这是一个指示客户端发送请求体的指令。

当请求已发送时触发。更具体地说，当请求头部和主体的最后一段已移交给操作系统以便通过网络传输时，会触发此事件。这并不意味着服务器已经收到了任何内容。

当服务器发送 1xx 中间响应时触发（不包括 101 升级）。此事件的监听器将接收一个对象，其中包含 HTTP 版本、状态码、状态消息、键值头部对象，以及包含原始头部名称及其各自值的数组。

import { request } from 'node:http';

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
};

// 发出请求
const req = request(options);
req.end();

req.on('information', (info) => {
  console.log(`在主响应之前收到信息：${info.statusCode}`);
});

const http = require('node:http');

const options = {
  host: '127.0.0.1',
  port: 8080,
  path: '/length_request',
};

// 发出请求
const req = http.request(options);
req.end();

req.on('information', (info) => {
  console.log(`在主响应之前收到信息：${info.statusCode}`);
});

101 升级状态不会触发此事件，因为它们打破了传统的 HTTP 请求/响应链，例如 WebSocket、原地 TLS 升级或 HTTP 2.0。要接收 101 升级通知，请改为监听 'upgrade' 事件。

当收到此请求的响应时触发。此事件仅触发一次。

除非用户指定了 net.Socket 以外的 socket 类型，否则保证此事件会传递一个 net.Socket 类的实例，它是 stream.Duplex 的子类。

当底层 socket 因无活动而超时时触发。这仅通知 socket 处于空闲状态。必须手动销毁请求。

另见：request.setTimeout()。

每当服务器响应带有升级的请求时触发。如果没有监听此事件且响应状态码为 101 协议切换，接收升级头部的客户端的连接将被关闭。

除非用户指定了 net.Socket 以外的 socket 类型，否则保证此事件会传递一个 net.Socket 类的实例，它是 stream.Duplex 的子类。

演示如何监听 'upgrade' 事件的客户端服务器配对示例。

import http from 'node:http';
import process from 'node:process';

// 创建一个 HTTP 服务器
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
server.on('upgrade', (req, stream, head) => {
  stream.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n');

  stream.pipe(stream); // 回显
});

// 现在服务器正在运行
server.listen(1337, '127.0.0.1', () => {

  // 发出请求
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      'Connection': 'Upgrade',
      'Upgrade': 'websocket',
    },
  };

  const req = http.request(options);
  req.end();

  req.on('upgrade', (res, stream, upgradeHead) => {
    console.log('已升级！');
    stream.end();
    process.exit(0);
  });
});

const http = require('node:http');

// 创建一个 HTTP 服务器
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
server.on('upgrade', (req, stream, head) => {
  stream.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
               'Upgrade: WebSocket\r\n' +
               'Connection: Upgrade\r\n' +
               '\r\n');

  stream.pipe(stream); // 回显
});

// 现在服务器正在运行
server.listen(1337, '127.0.0.1', () => {

  // 发出请求
  const options = {
    port: 1337,
    host: '127.0.0.1',
    headers: {
      'Connection': 'Upgrade',
      'Upgrade': 'websocket',
    },
  };

  const req = http.request(options);
  req.end();

  req.on('upgrade', (res, stream, upgradeHead) => {
    console.log('已升级！');
    stream.end();
    process.exit(0);
  });
});

稳定性：0 - 已废弃：请改用 request.destroy()。

将请求标记为中止。调用此方法将导致响应中的剩余数据被丢弃并且 socket 被销毁。

稳定性：0 - 已废弃。请改用检查 request.destroyed。

• 类型：boolean

如果请求已被中止，则 request.aborted 属性将为 true

稳定性：0 - 已废弃。请使用 request.socket。

• 类型：stream.Duplex

参见 request.socket。

参见 writable.cork()。

结束发送请求。如果主体的任何部分尚未发送，它会将这些部分冲刷到流中。如果请求采用分块传输编码，这将发送终止符 '0\r\n\r\n'。

如果指定了 data，则相当于调用 request.write(data, encoding)，然后调用 [request.end(callback)]。

如果指定了 callback，它将在请求流完成时被调用。

销毁请求。可选择触发 'error' 事件，并触发 'close' 事件。调用此方法会导致响应中的剩余数据被丢弃，并在使用了 socket 时销毁 socket；否则在可能的情况下将其返回到相应的 Agent 池。

详见 writable.destroy()。

• 类型：boolean

在调用 request.destroy() 后为 true。

详见 writable.destroyed。

稳定性：0 - 已废弃。请使用 request.writableEnded。

• 类型：boolean

如果调用了 request.end()，request.finished 属性将为 true。如果请求是通过 http.get() 发起的，request.end() 将被自动调用。

冲刷请求头部。

出于效率原因，Node.js 通常缓冲请求头部，直到调用 request.end() 或写入第一块请求数据。然后它尝试将请求头部和数据打包到单个 TCP 数据包中。

这通常是理想的（它节省了一次 TCP 往返），但当第一块数据直到可能更晚的时候才发送时则不然。request.flushHeaders() 绕过优化并启动请求。

读取请求上的一个头部。名称不区分大小写。返回值的类型取决于提供给 request.setHeader() 的参数。

request.setHeader('content-type', 'text/html');
request.setHeader('Content-Length', Buffer.byteLength(body));
request.setHeader('Cookie', ['type=ninja', 'language=javascript']);
const contentType = request.getHeader('Content-Type');
// 'contentType' 是 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' 是 number 类型
const cookie = request.getHeader('Cookie');
// 'cookie' 是 string[] 类型

request.getHeaderNames(): void

• 返回：string[]

返回一个包含当前传出头部唯一名称的数组。所有头部名称均为小写。

request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);

const headerNames = request.getHeaderNames();
// headerNames === ['foo', 'cookie']

request.getHeaders(): void

• 返回：Object

返回当前传出头部的浅拷贝。由于使用了浅拷贝，数组值可能会被变更，而无需额外调用各种头部相关的 http 模块方法。返回对象的键是头部名称，值是相应的头部值。所有头部名称均为小写。

request.getHeaders() 方法返回的对象 不 原型继承自 JavaScript Object。这意味着典型的 Object 方法（如 obj.toString()、obj.hasOwnProperty() 等）未定义且 将无法工作。

request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);

const headers = request.getHeaders();
// headers === { foo: 'bar', 'cookie': ['foo=bar', 'bar=baz'] }

request.getRawHeaderNames(): void

• 返回：string[]

返回一个包含当前传出原始头部唯一名称的数组。头部名称返回时保留其设置的确切大小写形式。

request.setHeader('Foo', 'bar');
request.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);

const headerNames = request.getRawHeaderNames();
// headerNames === ['Foo', 'Set-Cookie']

request.hasHeader(name): void

如果由 name 标识的头部当前已设置在传出头部中，则返回 true。头部名称匹配不区分大小写。

const hasContentType = request.hasHeader('content-type');

• 类型：number 默认值： 1000

限制响应头部的最大数量。超过此限制的响应将被拒绝，并返回 HPE_HEADER_OVERFLOW 错误。如果设置为 0，则不应用任何限制。

• 类型：string 请求路径。

• 类型：string 请求方法。

• 类型：string 请求主机。

• 类型：string 请求协议。

request.removeHeader(name): void

移除已在头部对象中定义的头部。

request.removeHeader('Content-Type');

• 类型：boolean 请求是否通过重用的套接字发送。

当通过启用了 keep-alive 的 agent 发送请求时，底层套接字可能会被重用。但如果服务器在不当时机关闭连接，客户端可能会遇到 'ECONNRESET' 错误。

import http from 'node:http';
const agent = new http.Agent({ keepAlive: true });

// 服务器默认有 5 秒的 keep-alive 超时
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // 使用一个 keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // 什么都不做
    });
  });
}, 5000); // 每 5 秒发送一次请求，以便更容易触发空闲超时

const http = require('node:http');
const agent = new http.Agent({ keepAlive: true });

// 服务器默认有 5 秒的 keep-alive 超时
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // 使用一个 keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // 什么都不做
    });
  });
}, 5000); // 每 5 秒发送一次请求，以便更容易触发空闲超时

通过标记请求是否重用了套接字，我们可以据此进行自动错误重试。

import http from 'node:http';
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      // 检查是否需要重试
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

const http = require('node:http');
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      // 检查是否需要重试
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

request.setHeader(name, value): void

为头部对象设置单个头部值。如果此头部已存在于待发送的头部中，其值将被替换。此处使用字符串数组来发送多个具有相同名称的头部。非字符串值将未经修改地存储。因此，request.getHeader() 可能返回非字符串值。但是，非字符串值将被转换为字符串以便网络传输。

request.setHeader('Content-Type', 'application/json');

或

request.setHeader('Cookie', ['type=ninja', 'language=javascript']);

当值为字符串时，如果它包含 latin1 编码之外的字符，将抛出异常。

如果需要在值中传递 UTF-8 字符，请使用 RFC 8187 标准对值进行编码。

const filename = 'Rock 🎵.txt';
request.setHeader('Content-Disposition', `attachment; filename*=utf-8''${encodeURIComponent(filename)}`);

request.setNoDelay(noDelay?): void

一旦将套接字分配给此请求并且连接已建立，便会调用 socket.setNoDelay()。

request.setSocketKeepAlive(enable?, initialDelay?): void

一旦将 socket 分配给此请求并完成连接，socket.setKeepAlive() 将被调用。

request.setTimeout(timeout, callback?): void

一旦将 socket 分配给此请求并完成连接，socket.setTimeout() 将被调用。

• 类型：stream.Duplex

指向底层 socket 的引用。通常用户不希望访问此属性。特别是，由于协议解析器附加到 socket 的方式，socket 不会触发 'readable' 事件。

import http from 'node:http';
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`你的 IP 地址是 ${ip}，源端口是 ${port}。`);
  // 消费响应对象
});

const http = require('node:http');
const options = {
  host: 'www.google.com',
};
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`你的 IP 地址是 ${ip}，源端口是 ${port}。`);
  // 消费响应对象
});

除非用户指定了 net.Socket 以外的 socket 类型，否则保证此属性是 net.Socket 类的实例，它是 stream.Duplex 的子类。

request.uncork(): void

参见 writable.uncork()。

• 类型：boolean

在调用 request.end() 后为 true。此属性不指示数据是否已冲刷，为此请改用 request.writableFinished。

• 类型：boolean

如果在 'finish' 事件触发之前，所有数据已刷写到底层系统，则为 true。

request.write(chunk, encoding?, callback?): void

发送一块主体数据。此方法可以调用多次。如果未设置 Content-Length，数据将自动以 HTTP 分块传输编码进行编码，以便服务器知道数据何时结束。将添加 Transfer-Encoding: chunked 头部。必须调用 request.end() 来完成发送请求。

encoding 参数是可选的，仅当 chunk 是字符串时适用。默认为 'utf8'。

callback 参数是可选的，当这块数据被冲刷时将被调用，但仅当这块数据非空时。

如果整个数据成功冲刷到内核缓冲区，则返回 true。如果全部或部分数据入队到用户内存，则返回 false。当缓冲区再次空闲时，将触发 'drain'。

当 write 函数使用空字符串或缓冲区调用时，它什么都不做并等待更多输入。

• 继承自：net.Server

每当收到带有 HTTP Expect: 100-continue 的请求时触发。 如果未监听此事件，服务器将会自动根据需要以 100 Continue 作出响应。

处理此事件时，如果客户端应继续发送请求主体，则需要调用 response.writeContinue()；如果客户端不应继续发送请求主体，则需要生成适当的 HTTP 响应（例如 400 错误请求）。

一旦该事件被触发并处理，'request' 事件将不会再触发。

每当收到带有 HTTP Expect 头部且其值不是 100-continue 的请求时触发。如果未监听此事件，服务器将会自动根据需要以 417 Expectation Failed 作出响应。

一旦该事件被触发并处理，'request' 事件将不会再触发。

如果客户端连接触发了 'error' 事件，就会转发到这里。 此事件的监听器负责关闭或销毁底层 socket。例如，使用自定义 HTTP 响应更优雅地关闭 socket，而不是突然中断连接，可能会更合适。处理程序在返回之前必须关闭或销毁该 socket。

除非用户指定了 net.Socket 以外的 socket 类型，否则此事件保证会传递 net.Socket 类的实例， 它是 stream.Duplex 的子类。

默认行为是尝试使用 HTTP '400 Bad Request' 关闭 socket，或者在发生 HPE_HEADER_OVERFLOW 错误时使用 HTTP '431 Request Header Fields Too Large'。如果 socket 不可写，或者当前附加的 http.ServerResponse 的头部已经发送，则会立即销毁它。

socket 是发生错误的 net.Socket 对象。

import http from 'node:http';

const server = http.createServer((req, res) => {
  res.end();
});
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});
server.listen(8000);

const http = require('node:http');

const server = http.createServer((req, res) => {
  res.end();
});
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});
server.listen(8000);

当发生 'clientError' 事件时，不存在 request 或 response 对象，因此发送的任何 HTTP 响应（包括响应头和有效载荷） 都必须直接写入 socket 对象。需要特别注意，确保该响应是格式正确的 HTTP 响应消息。

err 是 Error 的一个实例，并且有两个额外字段：

• bytesParsed：Node.js 可能已正确解析的请求数据包字节；
• rawPacket：当前请求的原始数据包。

在某些情况下，客户端已经收到了响应，和/或套接字 已经被销毁，例如 ECONNRESET 错误的情况。在尝试向套接字发送数据之前， 最好先检查它是否仍然可写。

server.on('clientError', (err, socket) => {
  if (err.code === 'ECONNRESET' || !socket.writable) {
    return;
  }

  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
});

当服务器关闭时触发。

每当客户端请求 HTTP CONNECT 方法时触发。如果没有监听此事件，请求 CONNECT 方法的客户端连接将被关闭。

除非用户指定的套接字类型不是 net.Socket，否则此事件保证传入 net.Socket 类的实例，而该类是 stream.Duplex 的子类。

在此事件触发后，请求的套接字将不再有 'data' 事件监听器，这意味着需要对其进行绑定，才能处理发送到服务器的数据。

当建立新的 TCP 流时触发。socket 通常是 net.Socket 类型的对象。通常不应直接访问此事件。特别是，由于协议解析器附加到套接字的方式，套接字不会触发 'readable' 事件。socket 也可以通过 request.socket 访问。

用户可以显式触发此事件，以将连接注入 HTTP 服务器。在这种情况下，可以传入任何 Duplex 流。

如果在此处调用 socket.setTimeout()，且 server.keepAliveTimeout 不为零，则在套接字处理完一个请求后，超时将被替换为 server.keepAliveTimeout。

除非用户指定的套接字类型不是 net.Socket，否则此事件保证传入 net.Socket 类的实例，而该类是 stream.Duplex 的子类。

当套接字上的请求数量达到 server.maxRequestsPerSocket 阈值时，服务器将放弃新的请求，改为触发 'dropRequest' 事件，并向客户端发送 503。

每当收到请求时都会触发。在一个连接中可能会有多个请求（在 HTTP Keep-Alive 连接的情况下）。

每当接受客户端的 HTTP 升级请求时触发。默认情况下，所有 HTTP 升级请求都会被忽略（也就是说，只会触发常规的 'request'`` 事件，从而保持正常的 HTTP 请求/响应流程），除非你监听此事件；在这种情况下，它们都会被接受（也就是说，会触发 'upgrade'事件，之后通信必须直接通过原始流继续）。你可以使用服务器的shouldUpgradeCallback` 选项更精确地控制此行为。

监听此事件是可选的；客户端不能强制更改协议。

如果 shouldUpgradeCallback 接受了升级，但没有注册任何事件处理器，套接字将被销毁，导致客户端立即关闭连接。

在极少数情况下，如果请求包含主体，那么主体将被正常解析并与升级后的流分离，而原始流数据只有在主体完成后才会开始。为确保在等待读取请求主体时不会阻塞对流的读取，对流的任何读取都会自动开始让请求主体流动。如果你想读取请求主体，请务必在开始读取升级后的流之前将其完成（也就是说，附加一个 'data' 监听器）。

流参数通常是请求所使用的 net.Socket 实例，但在某些情况下（例如存在请求主体时），它可能是一个双工流。如有必要，你可以通过 request.socket 访问请求的底层原始连接；只要用户没有指定其他套接字类型，该对象就保证是 net.Socket 的实例。

server.close(callback?): void

停止服务器接受新连接，并关闭所有连接到该服务器且既不发送请求也不等待响应的连接。 参见 net.Server.close()。

const http = require('node:http');

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
// 10 秒后关闭服务器
setTimeout(() => {
  server.close(() => {
    console.log('8000 端口上的服务器已成功关闭');
  });
}, 10000);

server.closeAllConnections(): void

关闭连接到此服务器的所有已建立 HTTP(S) 连接，包括正在发送请求或等待响应的活动连接。此方法 不会 销毁已升级到其他 协议的套接字，例如 WebSocket 或 HTTP/2。

这是一种强制关闭所有连接的方法，应谨慎使用。 与 server.close 一起使用时，建议在调用 server.close 之后再调用此方法，以避免在此调用与 server.close 调用之间创建新连接而产生竞争条件。

const http = require('node:http');

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: '你好，世界！',
  }));
});

server.listen(8000);
// 10 秒后关闭服务器
setTimeout(() => {
  server.close(() => {
    console.log('8000 端口上的服务器已成功关闭');
  });
  // 关闭所有连接以确保服务器成功关闭
  server.closeAllConnections();
}, 10000);

server.closeIdleConnections(): void

关闭此服务器上所有未在发送请求或等待响应的连接。

从 Node.js 19.0.0 开始，不再需要将此方法与 server.close 结合调用来回收 keep-alive 连接。使用它不会有坏处， 并且可以用于确保与需要支持 19.0.0 之前版本的库和应用程序保持向后兼容。 与 server.close 一起使用时，建议在调用 server.close 之后再调用此方法，以避免在本次调用和 server.close 调用之间创建新连接而导致的竞争条件。

const http = require('node:http');

const server = http.createServer({ keepAliveTimeout: 60000 }, (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);
// 10 秒后关闭服务器
setTimeout(() => {
  server.close(() => {
    console.log('端口 8000 上的服务器已成功关闭');
  });
  // 关闭空闲连接，例如 keep-alive 连接。一旦剩余的活动连接结束，服务器将关闭
  server.closeIdleConnections();
}, 10000);

• 类型：number 默认值： server.requestTimeout 和 60000 中较小的那个。

限制解析器等待接收完整 HTTP 标头的时间。

如果超时，服务器会返回 408 状态码，而不会将请求转发给请求监听器，然后关闭连接。

必须将其设置为非零值（例如 120 秒），以防在服务器未部署在 反向代理之后时遭受潜在的拒绝服务攻击。

server.listen(): void

开始监听 HTTP 服务器上的连接。
此方法与 server.listen() 在 net.Server 中完全相同。

• 类型：boolean 指示服务器是否正在监听连接。

• 类型：number 默认值： 1000

限制传入标头的最大数量。如果设置为 0，则不应用限制。

• 类型：number 默认值： 300000

设置接收客户端整个请求的超时时间（毫秒）。

如果超时，服务器会返回 408 状态码，而不会将请求转发给请求监听器，然后关闭连接。

必须将其设置为非零值（例如 120 秒），以防在服务器未部署在 反向代理之后时遭受潜在的拒绝服务攻击。

server.setTimeout(msecs?, callback?): void

设置套接字的超时时间，如果发生超时，则在 Server 对象上发出 'timeout' 事件，并将该套接字作为参数传递。

如果 Server 对象上存在 'timeout' 事件监听器，那么它会 以超时套接字作为参数被调用。

默认情况下，服务器不会让套接字超时。但是，如果为服务器的 'timeout' 事件 分配了回调函数，则必须显式处理超时。

• 类型：number 每个套接字的请求数。默认值： 0（无限制）

套接字在关闭 keep alive 连接之前所能处理的最大请求数。

值为 0 将禁用该限制。

达到限制后，它会将 Connection 标头值设置为 close，但实际上不会关闭连接。限制达到后发送的后续请求将收到 503 Service Unavailable 响应。

• 类型：number 超时时间（毫秒）。默认值： 0（无超时）

套接字在被视为超时之前处于非活动状态的毫秒数。

值为 0 将禁用传入连接的超时行为。

套接字超时逻辑在连接时设置，因此更改此值 只会影响到服务器的新连接，不会影响任何现有连接。

• 类型：number 超时时间（毫秒）。默认值： 65000（65 秒）。

服务器在写入最后一条响应后， 在销毁套接字之前，需要等待额外传入数据的毫秒数。

此超时值与 server.keepAliveTimeoutBuffer 选项配合使用，以以下方式确定实际 套接字超时： socketTimeout = keepAliveTimeout + keepAliveTimeoutBuffer 如果服务器在 keep-alive 超时触发之前收到额外数据， 它会重置常规空闲超时，即 server.timeout。

值为 0 将禁用传入连接上的 keep-alive 超时行为。 值为 0 会让 HTTP 服务器的行为类似于 Node.js 8.0.0 之前的版本， 那时没有 keep-alive 超时。

套接字超时逻辑在建立连接时就已设置，因此更改此值 只会影响到服务器上的新连接，不会影响任何现有连接。

• 类型：number 以毫秒为单位的超时时间。默认值： 1000（1 秒）。

要添加到 server.keepAliveTimeout 的额外缓冲时间，用于延长内部 套接字超时。

此缓冲有助于通过将套接字超时相对于公布的 keep-alive 超时略微 增加，从而减少连接重置（ECONNRESET）错误。

此选项仅适用于新的传入连接。

server[Symbol.asyncDispose](): void

调用 server.close() 并返回一个 promise，当服务器关闭时 该 promise 将被兑现。

• 继承：http.OutgoingMessage

此对象由 HTTP 服务器内部创建，而非由用户创建。它作为第二个参数传递给 'request' 事件。

表示响应已完成，或者其底层连接在响应完成之前被提前终止。

当响应已发送时触发。更具体地说，当响应头部和主体的最后一段已移交操作系统以便通过网络传输时，会触发此事件。这并不意味着客户端已经收到任何内容。

response.addTrailers(headers): void

此方法将 HTTP 尾部头（消息末尾的头）添加到响应中。

仅当响应使用分块编码时，尾部头 才会 被发出；如果不是（例如，如果请求是 HTTP/1.0），它们将被静默丢弃。

HTTP 要求发送 Trailer 头才能发出尾部头，其值中包含头部字段列表。例如，

response.writeHead(200, { 'Content-Type': 'text/plain',
                          'Trailer': 'Content-MD5' });
response.write(fileData);
response.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' });
response.end();

尝试设置包含无效字符的头部字段名或值将导致抛出 TypeError。

稳定性：0 - 已弃用。使用 response.socket。

• 类型：stream.Duplex

参见 response.socket。