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.Agent 实例。

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

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

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。确定 agent 可以打开多少个并发套接字。与 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();
    });
  });
});

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

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

当服务器发送 1xx 中间响应时触发（不包括 101 Upgrade）。此事件的监听器将接收一个对象，其中包含 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}`);
});

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

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

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

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

另见：request.setTimeout()。

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

除非用户指定了 <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);
  });
});

request.abort(): void

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

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

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

• 类型：<boolean>

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

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

• 类型：<stream.Duplex>

参见 request.socket。

request.cork(): void

参见 writable.cork()。

request.end(data?, encoding?, callback?): void

完成发送请求。如果主体的任何部分未发送，它将把它们冲刷到流中。如果请求是分块的，这将发送终止符 '0\r\n\r\n'。

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

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

request.destroy(error?): void

销毁请求。可选择触发 '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() 将被自动调用。

request.flushHeaders(): void

冲刷请求头部。

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

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

request.getHeader(name): void

读取请求上的一个头部。名称不区分大小写。返回值的类型取决于提供给 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> 默认： 2000

限制最大响应头部数量。如果设置为 0，则不应用限制。

• 类型：<string> 请求路径。

• 类型：<string> 请求方法。

• 类型：<string> 请求主机。

• 类型：<string> 请求协议。

request.removeHeader(name): void

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

request.removeHeader('Content-Type');

• 类型：<boolean> 请求是否通过重用的 socket 发送。

当通过启用了 keep-alive 的 agent 发送请求时，底层 socket 可能会被重用。但如果服务器在不当时机关闭连接，客户端可能会遇到 '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 秒发送一次请求，以便容易触发空闲超时

通过标记请求是否重用了 socket，我们可以基于此进行自动错误重试。

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

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 被分配给此请求并连接，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}。`);
  // 消费响应对象
});

除非用户指定了 <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 Bad Request）。

当此事件被触发并处理后，'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。如果 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);

当触发 'clientError' 事件时，不存在 request 或 response 对象，因此任何发送的 HTTP 响应，包括响应头和负载， 都_必须_直接写入 socket 对象。必须小心确保响应是格式正确的 HTTP 响应消息。

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

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

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

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> 的 socket 类型，否则该事件保证传入 <net.Socket> 类的实例， 它是 <stream.Duplex> 的子类。

此事件触发后，请求的 socket 将不再有 'data' 事件监听器，这意味着需要绑定它来处理 发送到该服务器的数据。

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

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

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

除非用户指定了不同于 <net.Socket> 的 socket 类型，否则该事件保证传入 <net.Socket> 类的实例， 它是 <stream.Duplex> 的子类。

当 socket 上的请求数量达到 server.maxRequestsPerSocket 的阈值时，服务器将丢弃新的请求， 转而触发 'dropRequest' 事件，然后向客户端发送 503。

每当有请求时触发。每个连接上可能有多个请求 （在 HTTP Keep-Alive 连接的情况下）。

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

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

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

在极少数请求包含正文的情况下，该正文会被 正常解析，并与升级流分离，而原始流数据 只会在其完成后开始。为确保从流中读取不会因等待 请求正文读取而被阻塞，对流的任何读取都会自动开始流动请求正文。如果你想读取 请求正文，请务必在开始读取升级流之前完成它（即附加一个 'data' 监听器）。

stream 参数通常是请求所使用的 <net.Socket> 实例，但在某些情况下（例如带有请求正文时），它可能是一个 duplex 流。如有必要，你可以通过 request.socket 访问请求的底层原始连接，只要用户没有指定其他 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) 连接，包括 连接到此服务器且正在发送请求或等待响应的活动连接。此方法_不会_销毁升级到其他 协议的 socket，例如 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: 'Hello World!',
  }));
});

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

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

如果超时到期，服务器会以 408 状态响应，而不会将请求转发给请求监听器，然后关闭连接。

它必须设置为非零值（例如 120 秒），以防止 在服务器未部署在反向代理后面时可能发生的 拒绝服务攻击。

server.listen(): void

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

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

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

如果超时到期，服务器会以 408 状态响应，而不会将请求转发给请求监听器，然后关闭连接。

它必须设置为非零值（例如 120 秒），以防止 在服务器未部署在反向代理后面时可能发生的 拒绝服务攻击。

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

设置 socket 的超时值，并在发生超时时在 Server 对象上触发 'timeout' 事件，并将 socket 作为参数传入。

如果 Server 对象上有 'timeout' 事件监听器，那么会 以超时的 socket 作为参数调用它。

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

socket 在关闭 keep alive 连接之前可处理的最大请求数。

值为 0 将禁用此限制。

达到限制时，会将 Connection 头的值设置为 close，但不会真正关闭连接；在达到限制后发送的后续请求将收到 503 Service Unavailable 响应。

socket 在被认为超时之前的不活动毫秒数。

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

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

服务器在完成写入最后一个响应后， 在销毁 socket 之前，需要等待额外传入数据的 毫秒数。

此超时值与 server.keepAliveTimeoutBuffer 选项结合使用，以确定实际的 socket 超时时间，计算方式为： socketTimeout = keepAliveTimeout + keepAliveTimeoutBuffer 如果服务器在 keep-alive 超时触发之前收到新数据，它将重置常规的不活动超时，即 server.timeout。

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

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

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

此缓冲区通过略微增加 socket 超时时间，相对于声明的 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。

response.cork(): void

参见 writable.cork()。

response.end(data?, encoding?, callback?): void

此方法向服务器发出信号，表明所有响应头部和主体都已发送；服务器应认为此消息已完成。每个响应都必须调用 response.end() 方法。

如果指定了 data，其效果类似于调用 response.write(data, encoding) 后跟 [response.end(callback)]。

如果指定了 callback，它将在响应流完成时调用。

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

• 类型：<boolean>

如果已调用 response.end()，则 response.finished 属性将为 true。

response.flushHeaders(): void

刷新响应头部。另参见：request.flushHeaders()。

response.getHeader(name): void

读取已排队但尚未发送给客户端的头部。名称不区分大小写。返回值的类型取决于提供给 response.setHeader() 的参数。

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

response.getHeaderNames(): void

• 返回：<string[]>

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

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

const headerNames = response.getHeaderNames();
// headerNames === ['foo', 'set-cookie']

response.getHeaders(): void

• 返回：<Object>

返回当前传出头部的浅拷贝。由于使用的是浅拷贝，数组值可以在不调用各种头部相关的 http 模块方法的情况下被突变。返回对象的键是头部名称，值是相应的头部值。所有头部名称均为小写。

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

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

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

response.hasHeader(name): void

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

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

• 类型：<boolean>

布尔值（只读）。如果已发送头部则为 true，否则为 false。

response.removeHeader(name): void

移除排队等待隐式发送的头部。

response.removeHeader('Content-Encoding');

• 类型：<http.IncomingMessage>

对原始 HTTP request 对象的引用。

• 类型：<boolean>

当为 true 时，如果头部中尚未存在 Date 头部，则会自动生成并在响应中发送 Date 头部。默认为 true。

这应仅用于测试；大多数 HTTP 响应都需要 Date 头部（详见 RFC 9110 Section 6.6.1）。

response.setHeader(name, value): void

返回响应对象。

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

response.setHeader('Content-Type', 'text/html');

或

response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);

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

当使用 response.setHeader() 设置头部时，它们将与传递给 response.writeHead() 的任何头部合并，传递给 response.writeHead() 的头部具有优先级。

// 返回 content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
});

如果调用了 response.writeHead() 方法且未调用此方法，它将直接把提供的头部值写入网络通道而不内部缓存，并且对该头部的 response.getHeader() 将不会产生预期结果。如果希望逐步填充头部以便将来检索和修改，请使用 response.setHeader() 而不是 response.writeHead()。

response.setTimeout(msecs, callback?): void

将 Socket 的超时值设置为 msecs。如果提供了 callback，则它作为监听器添加到响应对象的 'timeout' 事件上。

如果未将 'timeout' 监听器添加到请求、响应或服务器，则套接字在超时时会被销毁。如果处理程序分配给了请求、响应或服务器的 'timeout' 事件，则必须显式处理超时的套接字。

• 类型：<stream.Duplex>

对底层 socket 的引用。通常用户不希望访问此属性。特别是，由于协议解析器附加到 socket 的方式，socket 不会发出 'readable' 事件。在 response.end() 之后，该属性被置空。

import http from 'node:http';
const server = http.createServer((req, res) => {
  const ip = res.socket.remoteAddress;
  const port = res.socket.remotePort;
  res.end(`您的 IP 地址是 ${ip}，源端口是 ${port}。`);
}).listen(3000);

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

• 类型：<number> 默认： 200

当使用隐式头部（未显式调用 response.writeHead()）时，此属性控制在刷新头部时发送给客户端的状态码。

response.statusCode = 404;

在响应头部发送给客户端后，此属性指示发出的状态码。

• 类型：<string>

当使用隐式头部（未显式调用 response.writeHead()）时，此属性控制在刷新头部时发送给客户端的状态消息。如果此属性保持为 undefined，则将使用该状态码的标准消息。

response.statusMessage = 'Not found';

在响应头部发送给客户端后，此属性指示发出的状态消息。

• 类型：<boolean> 默认： false

如果设置为 true，Node.js 将检查 Content-Length 头部值与主体大小（以字节为单位）是否相等。Content-Length 头部值不匹配将导致抛出 Error，标识为 code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'。

response.uncork(): void

参见 writable.uncork()。

• 类型：<boolean>

在调用 response.end() 之后为 true。此属性不指示数据是否已刷新，为此请使用 response.writableFinished。

• 类型：<boolean>

如果所有数据都已刷新到底层系统，则在 'finish' 事件发出之前立即为 true。

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

如果调用了此方法且尚未调用 response.writeHead()，它将切换到隐式头部模式并刷新隐式头部。

这发送响应主体的一块。可以多次调用此方法以提供主体的连续部分。

如果在 createServer 中将 rejectNonStandardBodyWrites 设置为 true，则当请求方法或响应状态不支持内容时，不允许写入主体。如果尝试为 HEAD 请求写入主体或作为 204 或 304 响应的一部分写入主体，则会抛出代码为 ERR_HTTP_BODY_NOT_ALLOWED 的同步 Error。

chunk 可以是字符串或 buffer。如果 chunk 是字符串，则第二个参数指定如何将其编码为字节流。当这块数据被刷新时，将调用 callback。

这是原始 HTTP 主体，与可能使用的更高级的多部分主体编码无关。

第一次调用 response.write() 时，它将把缓冲的头部信息和第一块主体发送给客户端。第二次调用 response.write() 时，Node.js 假设数据将被流式传输，并单独发送新数据。也就是说，响应被缓冲到主体的第一块。

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

response.writeContinue(): void

向客户端发送 HTTP/1.1 100 Continue 消息，表示应发送请求主体。参见 Server 上的 'checkContinue' 事件。

response.writeEarlyHints(hints, callback?): void

向客户端发送带有 Link 头部的 HTTP/1.1 103 Early Hints 消息，指示用户代理可以预加载/预连接链接的资源。hints 是一个对象，包含要随 early hints 消息发送的头部值。可选的 callback 参数将在写入响应消息时调用。

示例

const earlyHintsLink = '</styles.css>; rel=preload; as=style';
response.writeEarlyHints({
  'link': earlyHintsLink,
});

const earlyHintsLinks = [
  '</styles.css>; rel=preload; as=style',
  '</scripts.js>; rel=preload; as=script',
];
response.writeEarlyHints({
  'link': earlyHintsLinks,
  'x-trace-id': 'id for diagnostics',
});

const earlyHintsCallback = () => console.log('早期提示消息已发送');
response.writeEarlyHints({
  'link': earlyHintsLinks,
}, earlyHintsCallback);

response.writeHead(statusCode, statusMessage?, headers?): void

向请求发送响应头。状态码是 3 位 HTTP 状态码，如 404。最后一个参数 headers 是响应头。可选地，可以将人类可读的 statusMessage 作为第二个参数给出。

headers 可以是一个 Array，其中键和值在同一列表中。它 不是 元组列表。因此，偶数偏移量是键值，奇数偏移量是关联值。数组格式与 request.rawHeaders 相同。

返回对 ServerResponse 的引用，以便调用可以链式进行。

const body = 'hello world';
response
  .writeHead(200, {
    'Content-Length': Buffer.byteLength(body),
    'Content-Type': 'text/plain',
  })
  .end(body);

此方法在消息上只能调用一次，且必须在调用 response.end() 之前调用。

如果在调用此之前调用了 response.write() 或 response.end()，则将计算隐式/可变头部并调用此函数。

当使用 response.setHeader() 设置头部时，它们将与传递给 response.writeHead() 的任何头部合并，传递给 response.writeHead() 的头部具有优先级。

如果调用了此方法且未调用 response.setHeader()，它将直接把提供的头部值写入网络通道而不内部缓存，并且对该头部的 response.getHeader() 将不会产生预期结果。如果希望逐步填充头部以便将来检索和修改，请使用 response.setHeader()。

// 返回 content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
});