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('got connected!');

    // 通过 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(`Got information prior to main response: ${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('got upgraded!');
    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 被销毁。

详见 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(`Your IP address is ${ip} and your source port is ${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 不可写或当前附加的 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' 事件。 socket 也可以在 request.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' 监听器）。

流参数通常是请求使用的 <net.Socket> 实例，但在某些情况下（例如带有请求主体），它可能是双工 流。如果需要，你可以通过 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) 连接，包括 连接到此服务器正在发送请求或等待响应的活动连接。这 不会 销毁升级到不同 协议（如 WebSocket 或 HTTP/2）的 socket。

这是一种强制关闭所有连接的方式，应谨慎使用。 每当与 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);

• 类型：<number> 默认值： server.requestTimeout 或 60000 之间的最小值。

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

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

必须将其设置为非零值（例如 120 秒），以便在服务器前面没有部署反向代理的情况下保护免受 潜在的拒绝服务攻击。

server.listen(): void

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

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

• 类型：<number> 默认值： 2000

限制最大传入头部计数。如果设置为 0，将不应用限制。

• 类型：<number> 默认值： 300000

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

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

必须将其设置为非零值（例如 120 秒），以便在服务器前面没有部署反向代理的情况下保护免受 潜在的拒绝服务攻击。

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

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

如果 Server 对象上有 'timeout' 事件监听器，则它将 使用超时的 socket 作为参数被调用。

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

• 类型：<number> 每个 socket 的请求数。 默认值： 0（无限制）

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

值 0 将禁用限制。

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

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

在 socket 被假定超时之前的不活动毫秒数。

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

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

• 类型：<number> 超时时间（毫秒）。 默认值： 5000（5 秒）。

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

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

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

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

• 类型：<number> 超时时间（毫秒）。 默认值： 1000（1 秒）。

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

此缓冲有助于通过略微增加超过广告 keep-alive 超时的 socket 超时时间来减少连接重置 (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(`Your IP address is ${ip} and your source port is ${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('early hints message sent');
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');
});