Node.js v18.20.0 文档

类：http.Agent#

¥Class: http.Agent

Agent 负责管理 HTTP 客户端连接的持久性和重用。它维护一个给定主机和端口的待处理请求队列，为每个请求重用单个套接字连接，直到队列为空，此时套接字要么被销毁，要么放入池中，在那里它会被再次用于请求到相同的主机和端口。是销毁还是汇集取决于 keepAlive 选项。

¥An Agent is responsible for managing connection persistence and reuse for HTTP clients. It maintains a queue of pending requests for a given host and port, reusing a single socket connection for each until the queue is empty, at which time the socket is either destroyed or put into a pool where it is kept to be used again for requests to the same host and port. Whether it is destroyed or pooled depends on the keepAlive option.

池化的连接会为其启用 TCP Keep-Alive，但服务器可能仍会关闭空闲连接，在这种情况下，它们将从池中删除，并在为该主机和端口触发新的 HTTP 请求时建立新连接。服务器也可能拒绝允许通过同一个连接的多个请求，在这种情况下，必须为每个请求重新建立连接，并且不能池化。Agent 仍将向该服务器触发请求，但每个请求都将通过新连接发生。

¥Pooled connections have TCP Keep-Alive enabled for them, but servers may still close idle connections, in which case they will be removed from the pool and a new connection will be made when a new HTTP request is made for that host and port. Servers may also refuse to allow multiple requests over the same connection, in which case the connection will have to be remade for every request and cannot be pooled. The Agent will still make the requests to that server, but each one will occur over a new connection.

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

¥When a connection is closed by the client or the server, it is removed from the pool. Any unused sockets in the pool will be unrefed so as not to keep the Node.js process running when there are no outstanding requests. (see socket.unref()).

一个很好的做法是，当不再使用时则 destroy() Agent 实例，因为未使用的套接字会消耗操作系统资源。

¥It is good practice, to destroy() an Agent instance when it is no longer in use, because unused sockets consume OS resources.

当套接字触发 'close' 事件或 'agentRemove' 事件时，则套接字将从代理中删除。当打算让 HTTP 请求长时间打开而不将其保留在代理中时，可以执行类似以下的操作：

¥Sockets are removed from an agent when the socket emits either a 'close' event or an 'agentRemove' event. When intending to keep one HTTP request open for a long time without keeping it in the agent, something like the following may be done:

http.get(options, (res) => {
  // Do stuff
}).on('socket', (socket) => {
  socket.emit('agentRemove');
}); 拷贝

代理也可用于单个请求。通过提供 {agent: false} 作为 http.get() 或 http.request() 函数的选项，则单次使用的具有默认选项的 Agent 将用于客户端连接。

¥An agent may also be used for an individual request. By providing {agent: false} as an option to the http.get() or http.request() functions, a one-time use Agent with default options will be used for the client connection.

agent:false：

http.get({
  hostname: 'localhost',
  port: 80,
  path: '/',
  agent: false,  // Create a new agent just for this one request
}, (res) => {
  // Do stuff with response
}); 拷贝

new Agent([options])#

• options <Object> 要在代理上设置的可配置选项集。可以有以下字段：

  ¥options <Object> Set of configurable options to set on the agent. Can have the following fields:

  • keepAlive <boolean> 即使没有未完成的请求，也要保留套接字，这样它们就可以用于未来的请求，而无需重新建立 TCP 连接。不要与 Connection 标头的 keep-alive 值混淆。使用代理时总是发送 Connection: keep-alive 标头，除非显式指定了 Connection 标头或当 keepAlive 和 maxSockets 选项分别设置为 false 和 Infinity，在这种情况下将使用 Connection: close。默认值：false。

    ¥keepAlive <boolean> Keep sockets around even when there are no outstanding requests, so they can be used for future requests without having to reestablish a TCP connection. Not to be confused with the keep-alive value of the Connection header. The Connection: keep-alive header is always sent when using an agent except when the Connection header is explicitly specified or when the keepAlive and maxSockets options are respectively set to false and Infinity, in which case Connection: close will be used. Default: false.

  • keepAliveMsecs <number> 使用 keepAlive 选项时，为 TCP Keep-Alive 数据包指定 初始延迟。当 keepAlive 选项为 false 或 undefined 时则忽略。默认值：1000。

    ¥keepAliveMsecs <number> When using the keepAlive option, specifies the initial delay for TCP Keep-Alive packets. Ignored when the keepAlive option is false or undefined. Default: 1000.

  • maxSockets <number> 每个主机允许的最大套接字数量。如果同一主机打开多个并发连接，则每个请求都将使用新的套接字，直到达到 maxSockets 值。如果主机尝试打开的连接数超过 maxSockets，则额外的请求将进入待处理请求队列，并在现有连接终止时进入活动连接状态。这确保在任何时间点，给定的主机最多有 maxSockets 个活动连接。默认值：Infinity。

    ¥maxSockets <number> Maximum number of sockets to allow per host. If the same host opens multiple concurrent connections, each request will use new socket until the maxSockets value is reached. If the host attempts to open more connections than maxSockets, the additional requests will enter into a pending request queue, and will enter active connection state when an existing connection terminates. This makes sure there are at most maxSockets active connections at any point in time, from a given host. Default: Infinity.

  • maxTotalSockets <number> 所有主机总共允许的最大套接字数量。每个请求将使用新的套接字，直到达到最大值。默认值：Infinity。

    ¥maxTotalSockets <number> Maximum number of sockets allowed for all hosts in total. Each request will use a new socket until the maximum is reached. Default: Infinity.

  • maxFreeSockets <number> 每台主机在空闲状态下保持打开的最大套接字数。仅当 keepAlive 设置为 true 时才相关。默认值：256。

    ¥maxFreeSockets <number> Maximum number of sockets per host to leave open in a free state. Only relevant if keepAlive is set to true. Default: 256.

  • scheduling <string> 选择下一个要使用的空闲套接字时应用的调度策略。它可以是 'fifo' 或 'lifo'。两种调度策略的主要区别在于 'lifo' 选择最近使用的套接字，而 'fifo' 选择最近最少使用的套接字。在每秒请求率较低的情况下，'lifo' 调度将降低选择可能因不活动而被服务器关闭的套接字的风险。在每秒请求率较高的情况下，'fifo' 调度将最大化打开套接字的数量，而 'lifo' 调度将保持尽可能低。默认值：'lifo'。

    ¥scheduling <string> Scheduling strategy to apply when picking the next free socket to use. It can be 'fifo' or 'lifo'. The main difference between the two scheduling strategies is that 'lifo' selects the most recently used socket, while 'fifo' selects the least recently used socket. In case of a low rate of request per second, the 'lifo' scheduling will lower the risk of picking a socket that might have been closed by the server due to inactivity. In case of a high rate of request per second, the 'fifo' scheduling will maximize the number of open sockets, while the 'lifo' scheduling will keep it as low as possible. Default: 'lifo'.

  • timeout <number> 套接字超时（以毫秒为单位）。这将在创建套接字时设置超时。

    ¥timeout <number> Socket timeout in milliseconds. This will set the timeout when the socket is created.

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

¥options in socket.connect() are also supported.

http.request() 使用的默认 http.globalAgent 将所有这些值设置为各自的默认值。

¥The default http.globalAgent that is used by http.request() has all of these values set to their respective defaults.

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

¥To configure any of them, a custom http.Agent instance must be created.

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])#

• options <Object> 包含连接详细信息的选项。查看 net.createConnection() 以获取选项的格式

  ¥options <Object> Options containing connection details. Check net.createConnection() for the format of the options

• callback <Function> 接收创建的套接字的回调函数

  ¥callback <Function> Callback function that receives the created socket

• 返回：<stream.Duplex>

  ¥Returns: <stream.Duplex>

生成用于 HTTP 请求的套接字/流。

¥Produces a socket/stream to be used for HTTP requests.

默认情况下，此函数与 net.createConnection() 相同。但是，如果需要更大的灵活性，自定义代理可能会覆盖此方法。

¥By default, this function is the same as net.createConnection(). However, custom agents may override this method in case greater flexibility is desired.

可以通过以下两种方式之一提供套接字/流：通过从此函数返回套接字/流，或将套接字/流传递给 callback。

¥A socket/stream can be supplied in one of two ways: by returning the socket/stream from this function, or by passing the socket/stream to callback.

此方法保证返回 <net.Socket> 类（<stream.Duplex> 的子类）的实例，除非用户指定 <net.Socket> 以外的套接字类型。

¥This method is guaranteed to return an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specifies a socket type other than <net.Socket>.

callback 的参数为 (err, stream)。

¥callback has a signature of (err, stream).

agent.keepSocketAlive(socket)#

• socket <stream.Duplex>

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

¥Called when socket is detached from a request and could be persisted by the Agent. Default behavior is to:

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

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

¥This method can be overridden by a particular Agent subclass. If this method returns a falsy value, the socket will be destroyed instead of persisting it for use with the next request.

socket 参数可以是 <net.Socket>（<stream.Duplex> 的子类）的实例。

¥The socket argument can be an instance of <net.Socket>, a subclass of <stream.Duplex>.

agent.reuseSocket(socket, request)#

• socket <stream.Duplex>

• request <http.ClientRequest>

当 socket 由于保持活动选项而持久化后附加到 request 时调用。默认行为是：

¥Called when socket is attached to request after being persisted because of the keep-alive options. Default behavior is to:

socket.ref(); 拷贝

此方法可以被特定的 Agent 子类覆盖。

¥This method can be overridden by a particular Agent subclass.

socket 参数可以是 <net.Socket>（<stream.Duplex> 的子类）的实例。

¥The socket argument can be an instance of <net.Socket>, a subclass of <stream.Duplex>.

agent.destroy()#

销毁代理当前正在使用的所有套接字。

¥Destroy any sockets that are currently in use by the agent.

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

¥It is usually not necessary to do this. However, if using an agent with keepAlive enabled, then it is best to explicitly shut down the agent when it is no longer needed. Otherwise, sockets might stay open for quite a long time before the server terminates them.

agent.freeSockets#

• <Object>

当启用 keepAlive 时，包含当前等待代理使用的套接字数组的对象。不要修改。

¥An object which contains arrays of sockets currently awaiting use by the agent when keepAlive is enabled. Do not modify.

freeSockets 列表中的套接字将被自动销毁并从 'timeout' 上的数组中删除。

¥Sockets in the freeSockets list will be automatically destroyed and removed from the array on 'timeout'.

agent.getName([options])#

• options <Object> 一组提供名称生成信息的选项

  ¥options <Object> A set of options providing information for name generation

  • host <string> 向其触发请求的服务器的域名或 IP 地址

    ¥host <string> A domain name or IP address of the server to issue the request to

  • port <number> 远程服务器端口

    ¥port <number> Port of remote server

  • localAddress <string> 触发请求时绑定网络连接的本地接口

    ¥localAddress <string> Local interface to bind for network connections when issuing the request

  • family <integer> 如果这不等于 undefined，则必须是 4 或 6。

    ¥family <integer> Must be 4 or 6 if this doesn't equal undefined.

• 返回：<string>

  ¥Returns: <string>

获取一组请求选项的唯一名称，以确定是否可以重用连接。对于 HTTP 代理，则这将返回 host:port:localAddress 或 host:port:localAddress:family。对于 HTTPS 代理，则名称包括 CA、证书、密码和其他确定套接字可重用性的 HTTPS/TLS 特定选项。

¥Get a unique name for a set of request options, to determine whether a connection can be reused. For an HTTP agent, this returns host:port:localAddress or host:port:localAddress:family. For an HTTPS agent, the name includes the CA, cert, ciphers, and other HTTPS/TLS-specific options that determine socket reusability.

agent.maxFreeSockets#

• <number>

默认设置为 256。对于启用了 keepAlive 的代理，这将设置在空闲状态下将保持打开的最大套接字数量。

¥By default set to 256. For agents with keepAlive enabled, this sets the maximum number of sockets that will be left open in the free state.

agent.maxSockets#

• <number>

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

¥By default set to Infinity. Determines how many concurrent sockets the agent can have open per origin. Origin is the returned value of agent.getName().

agent.maxTotalSockets#

• <number>

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

¥By default set to Infinity. Determines how many concurrent sockets the agent can have open. Unlike maxSockets, this parameter applies across all origins.

agent.requests#

• <Object>

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

¥An object which contains queues of requests that have not yet been assigned to sockets. Do not modify.

agent.sockets#

• <Object>

包含代理当前正在使用的套接字数组的对象。不要修改。

¥An object which contains arrays of sockets currently in use by the agent. Do not modify.

类：http.ClientRequest#

¥Class: http.ClientRequest

• 继承：<http.OutgoingMessage>

  ¥Extends: <http.OutgoingMessage>

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

¥This object is created internally and returned from http.request(). It represents an in-progress request whose header has already been queued. The header is still mutable using the setHeader(name, value), getHeader(name), removeHeader(name) API. The actual header will be sent along with the first data chunk or when calling request.end().

要获得响应，则将 'response' 的监听器添加到请求对象。当接收到响应头时，则请求对象会触发 'response'。'response' 事件使用一个参数执行，该参数是 http.IncomingMessage 的实例。

¥To get the response, add a listener for 'response' to the request object. 'response' will be emitted from the request object when the response headers have been received. The 'response' event is executed with one argument which is an instance of http.IncomingMessage.

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

¥During the 'response' event, one can add listeners to the response object; particularly to listen for the 'data' event.

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

¥If no 'response' handler is added, then the response will be entirely discarded. However, if a 'response' event handler is added, then the data from the response object must be consumed, either by calling response.read() whenever there is a 'readable' event, or by adding a 'data' handler, or by calling the .resume() method. Until the data is consumed, the 'end' event will not fire. Also, until the data is read it will consume memory that can eventually lead to a 'process out of memory' error.

为了向后兼容，如果注册了 'error' 监听器，则 res 只会触发 'error'。

¥For backward compatibility, res will only emit 'error' if there is an 'error' listener registered.

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

¥Set Content-Length header to limit the response body size. If response.strictContentLength is set to true, mismatching the Content-Length header value will result in an Error being thrown, identified by code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

Content-Length 值应该以字节为单位，而不是字符。使用 Buffer.byteLength() 来确定正文的长度（以字节为单位）。

¥Content-Length value should be in bytes, not characters. Use Buffer.byteLength() to determine the length of the body in bytes.

事件：'abort'#

¥Event: 'abort'

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

¥Emitted when the request has been aborted by the client. This event is only emitted on the first call to abort().

事件：'close'#

¥Event: 'close'

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

¥Indicates that the request is completed, or its underlying connection was terminated prematurely (before the response completion).

事件：'connect'#

¥Event: 'connect'

• response <http.IncomingMessage>

• socket <stream.Duplex>

• head <Buffer>

每次服务器使用 CONNECT 方法响应请求时触发。如果未监听此事件，则接收 CONNECT 方法的客户端将关闭其连接。

¥Emitted each time a server responds to a request with a CONNECT method. If this event is not being listened for, clients receiving a CONNECT method will have their connections closed.

除非用户指定 <net.Socket> 以外的套接字类型，否则此事件保证传入 <net.Socket> 类（<stream.Duplex> 的子类）的实例。

¥This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specifies a socket type other than <net.Socket>.

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

¥A client and server pair demonstrating how to listen for the 'connect' event:

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

// Create an HTTP tunneling proxy
const proxy = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connect to an origin server
  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);
  });
});

// Now that proxy is running
proxy.listen(1337, '127.0.0.1', () => {

  // Make a request to a tunneling proxy
  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!');

    // Make a request over an HTTP tunnel
    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');

// Create an HTTP tunneling proxy
const proxy = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('okay');
});
proxy.on('connect', (req, clientSocket, head) => {
  // Connect to an origin server
  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);
  });
});

// Now that proxy is running
proxy.listen(1337, '127.0.0.1', () => {

  // Make a request to a tunneling proxy
  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('got connected!');

    // Make a request over an HTTP tunnel
    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();
    });
  });
});拷贝

事件：'continue'#

¥Event: 'continue'

当服务器发送 '100 继续' HTTP 响应时触发，通常是因为请求包含“Expect:100-继续'。这是客户端应该发送请求正文的指令。

¥Emitted when the server sends a '100 Continue' HTTP response, usually because the request contained 'Expect: 100-continue'. This is an instruction that the client should send the request body.

事件：'finish'#

¥Event: 'finish'

当发送请求时触发。更具体地说，当响应头和正文的最后一段已移交给操作系统以通过网络传输时，则将触发此事件。这并不意味着服务器已经收到任何东西。

¥Emitted when the request has been sent. More specifically, this event is emitted when the last segment of the response headers and body have been handed off to the operating system for transmission over the network. It does not imply that the server has received anything yet.

事件：'information'#

¥Event: 'information'

• info <Object>

  • httpVersion <string>

  • httpVersionMajor <integer>

  • httpVersionMinor <integer>

  • statusCode <integer>

  • statusMessage <string>

  • headers <Object>

  • rawHeaders <string[]>

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

¥Emitted when the server sends a 1xx intermediate response (excluding 101 Upgrade). The listeners of this event will receive an object containing the HTTP version, status code, status message, key-value headers object, and array with the raw header names followed by their respective values.

import { request } from 'node:http';

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

// Make a request
const req = request(options);
req.end();

req.on('information', (info) => {
  console.log(`Got information prior to main response: ${info.statusCode}`);
});const http = require('node:http');

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

// Make a request
const req = http.request(options);
req.end();

req.on('information', (info) => {
  console.log(`Got information prior to main response: ${info.statusCode}`);
});拷贝

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

¥101 Upgrade statuses do not fire this event due to their break from the traditional HTTP request/response chain, such as web sockets, in-place TLS upgrades, or HTTP 2.0. To be notified of 101 Upgrade notices, listen for the 'upgrade' event instead.

事件：'response'#

¥Event: 'response'

• response <http.IncomingMessage>

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

¥Emitted when a response is received to this request. This event is emitted only once.

事件：'socket'#

¥Event: 'socket'

• socket <stream.Duplex>

除非用户指定 <net.Socket> 以外的套接字类型，否则此事件保证传入 <net.Socket> 类（<stream.Duplex> 的子类）的实例。

¥This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specifies a socket type other than <net.Socket>.

事件：'timeout'#

¥Event: 'timeout'

当底层套接字因不活动而超时时触发。这仅通知套接字已空闲。必须手动销毁请求。

¥Emitted when the underlying socket times out from inactivity. This only notifies that the socket has been idle. The request must be destroyed manually.

也可以看看：request.setTimeout()。

¥See also: request.setTimeout().

事件：'upgrade'#

¥Event: 'upgrade'

• response <http.IncomingMessage>

• socket <stream.Duplex>

• head <Buffer>

每次服务器响应升级请求时触发。如果未监听此事件且响应状态码为 101 Switching Protocols，则接收升级标头的客户端将关闭其连接。

¥Emitted each time a server responds to a request with an upgrade. If this event is not being listened for and the response status code is 101 Switching Protocols, clients receiving an upgrade header will have their connections closed.

除非用户指定 <net.Socket> 以外的套接字类型，否则此事件保证传入 <net.Socket> 类（<stream.Duplex> 的子类）的实例。

¥This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specifies a socket type other than <net.Socket>.

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

¥A client server pair demonstrating how to listen for the 'upgrade' event.

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

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

  socket.pipe(socket); // echo back
});

// Now that server is running
server.listen(1337, '127.0.0.1', () => {

  // make a request
  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, socket, upgradeHead) => {
    console.log('got upgraded!');
    socket.end();
    process.exit(0);
  });
});const http = require('node:http');

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

  socket.pipe(socket); // echo back
});

// Now that server is running
server.listen(1337, '127.0.0.1', () => {

  // make a request
  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, socket, upgradeHead) => {
    console.log('got upgraded!');
    socket.end();
    process.exit(0);
  });
});拷贝

request.abort()#

将请求标记为中止。调用它会导致响应中的剩余数据被丢弃并销毁套接字。

¥Marks the request as aborting. Calling this will cause remaining data in the response to be dropped and the socket to be destroyed.

request.aborted#

• <boolean>

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

¥The request.aborted property will be true if the request has been aborted.

request.connection#

• <stream.Duplex>

参见 request.socket。

¥See request.socket.

request.cork()#

参见 writable.cork()。

¥See writable.cork().

request.end([data[, encoding]][, callback])#

• data <string> | <Buffer> | <Uint8Array>

• encoding <string>

• callback <Function>

• 返回：<this>

  ¥Returns: <this>

完成发送请求。如果正文的任何部分未发送，则会将它们刷新到流中。如果请求被分块，则将发送终止的 '0\r\n\r\n'。

¥Finishes sending the request. If any parts of the body are unsent, it will flush them to the stream. If the request is chunked, this will send the terminating '0\r\n\r\n'.

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

¥If data is specified, it is equivalent to calling request.write(data, encoding) followed by request.end(callback).

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

¥If callback is specified, it will be called when the request stream is finished.

request.destroy([error])#

• error <Error> 可选，与 'error' 事件一起触发的错误。

  ¥error <Error> Optional, an error to emit with 'error' event.

• 返回：<this>

  ¥Returns: <this>

销毁请求。可选地触发 'error' 事件，并触发 'close' 事件。调用它会导致响应中的剩余数据被丢弃并销毁套接字。

¥Destroy the request. Optionally emit an 'error' event, and emit a 'close' event. Calling this will cause remaining data in the response to be dropped and the socket to be destroyed.

有关详细信息，请参阅 writable.destroy()。

¥See writable.destroy() for further details.

request.destroyed#

• <boolean>

在调用 request.destroy() 之后是 true。

¥Is true after request.destroy() has been called.

有关详细信息，请参阅 writable.destroyed。

¥See writable.destroyed for further details.

request.finished#

• <boolean>

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

¥The request.finished property will be true if request.end() has been called. request.end() will automatically be called if the request was initiated via http.get().

request.flushHeaders()#

刷新请求头。

¥Flushes the request headers.

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

¥For efficiency reasons, Node.js normally buffers the request headers until request.end() is called or the first chunk of request data is written. It then tries to pack the request headers and data into a single TCP packet.

这通常是需要的（节省了 TCP 往返），但是当第一个数据直到可能很晚才发送时才需要。request.flushHeaders() 绕过优化并启动请求。

¥That's usually desired (it saves a TCP round-trip), but not when the first data is not sent until possibly much later. request.flushHeaders() bypasses the optimization and kickstarts the request.

request.getHeader(name)#

• name <string>

• 返回：<any>

  ¥Returns: <any>

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

¥Reads out a header on the request. The name is case-insensitive. The type of the return value depends on the arguments provided to 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' is 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' is of type number
const cookie = request.getHeader('Cookie');
// 'cookie' is of type string[] 拷贝

request.getHeaderNames()#

• 返回：<string[]>

  ¥Returns: <string[]>

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

¥Returns an array containing the unique names of the current outgoing headers. All header names are lowercase.

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

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

request.getHeaders()#

• 返回：<Object>

  ¥Returns: <Object>

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

¥Returns a shallow copy of the current outgoing headers. Since a shallow copy is used, array values may be mutated without additional calls to various header-related http module methods. The keys of the returned object are the header names and the values are the respective header values. All header names are lowercase.

request.getHeaders() 方法返回的对象不是原型继承自 JavaScript Object。这意味着 obj.toString()、obj.hasOwnProperty() 等典型的 Object 方法没有定义，将不起​​作用。

¥The object returned by the request.getHeaders() method does not prototypically inherit from the JavaScript Object. This means that typical Object methods such as obj.toString(), obj.hasOwnProperty(), and others are not defined and will not work.

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

• 返回：<string[]>

  ¥Returns: <string[]>

返回包含当前传出原始标头的唯一名称的数组。标头名称返回并设置了它们的确切大小写。

¥Returns an array containing the unique names of the current outgoing raw headers. Header names are returned with their exact casing being set.

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

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

request.hasHeader(name)#

• name <string>

• 返回：<boolean>

  ¥Returns: <boolean>

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

¥Returns true if the header identified by name is currently set in the outgoing headers. The header name matching is case-insensitive.

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

request.maxHeadersCount#

• <number> 默认值：2000

  ¥<number> Default: 2000

限制最大响应头计数。如果设置为 0，则不会应用任何限制。

¥Limits maximum response headers count. If set to 0, no limit will be applied.

request.path#

• <string> 请求路径。

  ¥<string> The request path.

request.method#

• <string> 请求方法。

  ¥<string> The request method.

request.host#

• <string> 请求主机。

  ¥<string> The request host.

request.protocol#

• <string> 请求协议。

  ¥<string> The request protocol.

request.removeHeader(name)#

• name <string>

删除已定义到标头对象中的标头。

¥Removes a header that's already defined into headers object.

request.removeHeader('Content-Type'); 拷贝

request.reusedSocket#

• <boolean> 请求是否通过重用套接字发送。

  ¥<boolean> Whether the request is send through a reused socket.

当通过启用保持活动的代理发送请求时，可能会重用底层套接字。但是如果服务器在不幸的时候关闭连接，客户端可能会遇到 'ECONNRESET' 错误。

¥When sending request through a keep-alive enabled agent, the underlying socket might be reused. But if server closes connection at unfortunate time, client may run into a 'ECONNRESET' error.

import http from 'node:http';

// Server has a 5 seconds keep-alive timeout by default
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adapting a keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Do nothing
    });
  });
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeoutconst http = require('node:http');

// Server has a 5 seconds keep-alive timeout by default
http
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  })
  .listen(3000);

setInterval(() => {
  // Adapting a keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Do nothing
    });
  });
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeout拷贝

通过标记请求是否重用套接字，可以基于它进行自动错误重试。

¥By marking a request whether it reused socket or not, we can do automatic error retry base on it.

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) => {
      // Check if retry is needed
      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) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();拷贝

request.setHeader(name, value)#

• name <string>

• value <any>

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

¥Sets a single header value for headers object. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings here to send multiple headers with the same name. Non-string values will be stored without modification. Therefore, request.getHeader() may return non-string values. However, the non-string values will be converted to strings for network transmission.

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

或者

¥or

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

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

¥When the value is a string an exception will be thrown if it contains characters outside the latin1 encoding.

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

¥If you need to pass UTF-8 characters in the value please encode the value using the RFC 8187 standard.

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

request.setNoDelay([noDelay])#

• noDelay <boolean>

一旦套接字被分配给这个请求并被连接，则 socket.setNoDelay() 将被调用。

¥Once a socket is assigned to this request and is connected socket.setNoDelay() will be called.

request.setSocketKeepAlive([enable][, initialDelay])#

• enable <boolean>

• initialDelay <number>

一旦套接字被分配给这个请求并被连接，则 socket.setKeepAlive() 将被调用。

¥Once a socket is assigned to this request and is connected socket.setKeepAlive() will be called.

request.setTimeout(timeout[, callback])#

• timeout <number> 请求超时前的毫秒数。

  ¥timeout <number> Milliseconds before a request times out.

• callback <Function> 发生超时时要调用的可选函数。与绑定到 'timeout' 事件相同。

  ¥callback <Function> Optional function to be called when a timeout occurs. Same as binding to the 'timeout' event.

• 返回：<http.ClientRequest>

  ¥Returns: <http.ClientRequest>

一旦套接字被分配给这个请求并被连接，则 socket.setTimeout() 将被调用。

¥Once a socket is assigned to this request and is connected socket.setTimeout() will be called.

request.socket#

• <stream.Duplex>

对底层套接字的引用。通常用户不会想要访问这个属性。特别是，由于协议解析器附加到套接字的方式，套接字将不会触发 'readable' 事件。

¥Reference to the underlying socket. Usually users will not want to access this property. In particular, the socket will not emit 'readable' events because of how the protocol parser attaches to the socket.

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}.`);
  // Consume response object
});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(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});拷贝

该属性保证是 <net.Socket> 类（<stream.Duplex> 的子类）的实例，除非用户指定了 <net.Socket> 以外的套接字类型。

¥This property is guaranteed to be an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specified a socket type other than <net.Socket>.

request.uncork()#

参见 writable.uncork()。

¥See writable.uncork().

request.writableEnded#

• <boolean>

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

¥Is true after request.end() has been called. This property does not indicate whether the data has been flushed, for this use request.writableFinished instead.

request.writableFinished#

• <boolean>

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

¥Is true if all data has been flushed to the underlying system, immediately before the 'finish' event is emitted.

request.write(chunk[, encoding][, callback])#

• chunk <string> | <Buffer> | <Uint8Array>

• encoding <string>

• callback <Function>

• 返回：<boolean>

  ¥Returns: <boolean>

发送一块正文。此方法可以被多次调用。如果没有设置 Content-Length，则数据将自动使用 HTTP 分块传输编码进行编码，以便服务器知道数据何时结束。Transfer-Encoding: chunked 标头会被添加。需要调用 request.end() 来完成发送请求。

¥Sends a chunk of the body. This method can be called multiple times. If no Content-Length is set, data will automatically be encoded in HTTP Chunked transfer encoding, so that server knows when the data ends. The Transfer-Encoding: chunked header is added. Calling request.end() is necessary to finish sending the request.

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

¥The encoding argument is optional and only applies when chunk is a string. Defaults to 'utf8'.

callback 参数是可选的，将在刷新此数据块时调用，但前提是该块非空。

¥The callback argument is optional and will be called when this chunk of data is flushed, but only if the chunk is non-empty.

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

¥Returns true if the entire data was flushed successfully to the kernel buffer. Returns false if all or part of the data was queued in user memory. 'drain' will be emitted when the buffer is free again.

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

¥When write function is called with empty string or buffer, it does nothing and waits for more input.

类：http.Server#

¥Class: http.Server

• 继承：<net.Server>

  ¥Extends: <net.Server>

事件：'checkContinue'#

¥Event: 'checkContinue'

• request <http.IncomingMessage>

• response <http.ServerResponse>

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

¥Emitted each time a request with an HTTP Expect: 100-continue is received. If this event is not listened for, the server will automatically respond with a 100 Continue as appropriate.

如果客户端应该继续发送请求正文，则处理此事件涉及调用 response.writeContinue()，或者如果客户端不应该继续发送请求正文，则生成适当的 HTTP 响应（例如 400 Bad Request）。

¥Handling this event involves calling response.writeContinue() if the client should continue to send the request body, or generating an appropriate HTTP response (e.g. 400 Bad Request) if the client should not continue to send the request body.

处理和处理此事件时，不会触发 'request' 事件。

¥When this event is emitted and handled, the 'request' event will not be emitted.

事件：'checkExpectation'#

¥Event: 'checkExpectation'

• request <http.IncomingMessage>

• response <http.ServerResponse>

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

¥Emitted each time a request with an HTTP Expect header is received, where the value is not 100-continue. If this event is not listened for, the server will automatically respond with a 417 Expectation Failed as appropriate.

处理和处理此事件时，不会触发 'request' 事件。

¥When this event is emitted and handled, the 'request' event will not be emitted.

事件：'clientError'#

¥Event: 'clientError'

• exception <Error>

• socket <stream.Duplex>

如果客户端连接触发 'error' 事件，则会在此处转发。此事件的监听器负责关闭/销毁底层套接字。例如，可能希望使用自定义 HTTP 响应更优雅地关闭套接字，而不是突然切断连接。在监听器结束之前必须关闭或销毁套接字。

¥If a client connection emits an 'error' event, it will be forwarded here. Listener of this event is responsible for closing/destroying the underlying socket. For example, one may wish to more gracefully close the socket with a custom HTTP response instead of abruptly severing the connection. The socket must be closed or destroyed before the listener ends.

除非用户指定 <net.Socket> 以外的套接字类型，否则此事件保证传入 <net.Socket> 类（<stream.Duplex> 的子类）的实例。

¥This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specifies a socket type other than <net.Socket>.

默认行为是尝试使用 HTTP '400 错误请求' 关闭套接字，或在发生 HPE_HEADER_OVERFLOW 错误时使用 HTTP '431 请求标头字段太大'。如果套接字不可写或当前附加的 http.ServerResponse 的标头已发送，则立即销毁。

¥Default behavior is to try close the socket with a HTTP '400 Bad Request', or a HTTP '431 Request Header Fields Too Large' in the case of a HPE_HEADER_OVERFLOW error. If the socket is not writable or headers of the current attached http.ServerResponse has been sent, it is immediately destroyed.

socket 是错误源自的 net.Socket 对象。

¥socket is the net.Socket object that the error originated from.

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 响应消息。

¥When the 'clientError' event occurs, there is no request or response object, so any HTTP response sent, including response headers and payload, must be written directly to the socket object. Care must be taken to ensure the response is a properly formatted HTTP response message.

err 是 Error 的实例，有两个额外的列：

¥err is an instance of Error with two extra columns:

• bytesParsed：Node.js 可能正确解析的请求数据包的字节数；

  ¥bytesParsed: the bytes count of request packet that Node.js may have parsed correctly;

• rawPacket：当前请求的原始数据包。

  ¥rawPacket: the raw packet of current request.

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

¥In some cases, the client has already received the response and/or the socket has already been destroyed, like in case of ECONNRESET errors. Before trying to send data to the socket, it is better to check that it is still writable.

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

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

事件：'close'#

¥Event: 'close'

服务器关闭时触发。

¥Emitted when the server closes.

事件：'connect'#

¥Event: 'connect'

• request <http.IncomingMessage> HTTP 请求的参数，如它在 'request' 事件中

  ¥request <http.IncomingMessage> Arguments for the HTTP request, as it is in the 'request' event

• socket <stream.Duplex> 服务器和客户端之间的网络套接字

  ¥socket <stream.Duplex> Network socket between the server and client

• head <Buffer> 隧道流的第一个数据包（可能为空）

  ¥head <Buffer> The first packet of the tunneling stream (may be empty)

每次客户端请求 HTTP CONNECT 方法时触发。如果未监听此事件，则请求 CONNECT 方法的客户端将关闭其连接。

¥Emitted each time a client requests an HTTP CONNECT method. If this event is not listened for, then clients requesting a CONNECT method will have their connections closed.

除非用户指定 <net.Socket> 以外的套接字类型，否则此事件保证传入 <net.Socket> 类（<stream.Duplex> 的子类）的实例。

¥This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specifies a socket type other than <net.Socket>.

触发此事件后，请求的套接字将没有 'data' 事件监听器，这意味着需要绑定它才能处理发送到该套接字上的服务器的数据。

¥After this event is emitted, the request's socket will not have a 'data' event listener, meaning it will need to be bound in order to handle data sent to the server on that socket.

事件：'connection'#

¥Event: 'connection'

• socket <stream.Duplex>

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

¥This event is emitted when a new TCP stream is established. socket is typically an object of type net.Socket. Usually users will not want to access this event. In particular, the socket will not emit 'readable' events because of how the protocol parser attaches to the socket. The socket can also be accessed at request.socket.

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

¥This event can also be explicitly emitted by users to inject connections into the HTTP server. In that case, any Duplex stream can be passed.

如果此处调用 socket.setTimeout()，则当套接字已服务请求时（如果 server.keepAliveTimeout 非零）超时将替换为 server.keepAliveTimeout。

¥If socket.setTimeout() is called here, the timeout will be replaced with server.keepAliveTimeout when the socket has served a request (if server.keepAliveTimeout is non-zero).

除非用户指定 <net.Socket> 以外的套接字类型，否则此事件保证传入 <net.Socket> 类（<stream.Duplex> 的子类）的实例。

¥This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specifies a socket type other than <net.Socket>.

事件：'dropRequest'#

¥Event: 'dropRequest'

• request <http.IncomingMessage> HTTP 请求的参数，如它在 'request' 事件中

  ¥request <http.IncomingMessage> Arguments for the HTTP request, as it is in the 'request' event

• socket <stream.Duplex> 服务器和客户端之间的网络套接字

  ¥socket <stream.Duplex> Network socket between the server and client

当套接字上的请求数达到 server.maxRequestsPerSocket 的阈值时，服务器会丢弃新的请求并触发 'dropRequest' 事件，然后将 503 发送给客户端。

¥When the number of requests on a socket reaches the threshold of server.maxRequestsPerSocket, the server will drop new requests and emit 'dropRequest' event instead, then send 503 to client.

事件：'request'#

¥Event: 'request'

• request <http.IncomingMessage>

• response <http.ServerResponse>

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

¥Emitted each time there is a request. There may be multiple requests per connection (in the case of HTTP Keep-Alive connections).

事件：'upgrade'#

¥Event: 'upgrade'

• request <http.IncomingMessage> HTTP 请求的参数，如它在 'request' 事件中

  ¥request <http.IncomingMessage> Arguments for the HTTP request, as it is in the 'request' event

• socket <stream.Duplex> 服务器和客户端之间的网络套接字

  ¥socket <stream.Duplex> Network socket between the server and client

• head <Buffer> 升级流的第一个数据包（可能为空）

  ¥head <Buffer> The first packet of the upgraded stream (may be empty)

每次客户端请求 HTTP 升级时触发。监听此事件是可选的，客户端不能坚持协议更改。

¥Emitted each time a client requests an HTTP upgrade. Listening to this event is optional and clients cannot insist on a protocol change.

触发此事件后，请求的套接字将没有 'data' 事件监听器，这意味着需要绑定它才能处理发送到该套接字上的服务器的数据。

¥After this event is emitted, the request's socket will not have a 'data' event listener, meaning it will need to be bound in order to handle data sent to the server on that socket.

除非用户指定 <net.Socket> 以外的套接字类型，否则此事件保证传入 <net.Socket> 类（<stream.Duplex> 的子类）的实例。

¥This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specifies a socket type other than <net.Socket>.

server.close([callback])#

• callback <Function>

阻止服务器接受新连接。参见 net.Server.close()。

¥Stops the server from accepting new connections. See net.Server.close().

server.closeAllConnections()#

关闭所有连接到此服务器的连接。

¥Closes all connections connected to this server.

server.closeIdleConnections()#

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

¥Closes all connections connected to this server which are not sending a request or waiting for a response.

server.headersTimeout#

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

  ¥<number> Default: The minimum between server.requestTimeout or 60000.

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

¥Limit the amount of time the parser will wait to receive the complete HTTP headers.

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

¥If the timeout expires, the server responds with status 408 without forwarding the request to the request listener and then closes the connection.

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

¥It must be set to a non-zero value (e.g. 120 seconds) to protect against potential Denial-of-Service attacks in case the server is deployed without a reverse proxy in front.

server.listen()#

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

¥Starts the HTTP server listening for connections. This method is identical to server.listen() from net.Server.

server.listening#

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

  ¥<boolean> Indicates whether or not the server is listening for connections.

server.maxHeadersCount#

• <number> 默认值：2000

  ¥<number> Default: 2000

限制最大传入标头计数。如果设置为 0，则不会应用任何限制。

¥Limits maximum incoming headers count. If set to 0, no limit will be applied.

server.requestTimeout#

• <number> 默认值：300000

  ¥<number> Default: 300000

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

¥Sets the timeout value in milliseconds for receiving the entire request from the client.

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

¥If the timeout expires, the server responds with status 408 without forwarding the request to the request listener and then closes the connection.

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

¥It must be set to a non-zero value (e.g. 120 seconds) to protect against potential Denial-of-Service attacks in case the server is deployed without a reverse proxy in front.

server.setTimeout([msecs][, callback])#

• msecs <number> 默认值：0（无超时）

  ¥msecs <number> Default: 0 (no timeout)

• callback <Function>

• 返回：<http.Server>

  ¥Returns: <http.Server>

设置套接字的超时值，并在服务器对象上触发 'timeout' 事件，如果发生超时，则将套接字作为参数传入。

¥Sets the timeout value for sockets, and emits a 'timeout' event on the Server object, passing the socket as an argument, if a timeout occurs.

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

¥If there is a 'timeout' event listener on the Server object, then it will be called with the timed-out socket as an argument.

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

¥By default, the Server does not timeout sockets. However, if a callback is assigned to the Server's 'timeout' event, timeouts must be handled explicitly.

server.maxRequestsPerSocket#

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

  ¥<number> Requests per socket. Default: 0 (no limit)

关闭保持活动的连接之前，套接字可以处理的最大请求数。

¥The maximum number of requests socket can handle before closing keep alive connection.

0 值将禁用限制。

¥A value of 0 will disable the limit.

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

¥When the limit is reached it will set the Connection header value to close, but will not actually close the connection, subsequent requests sent after the limit is reached will get 503 Service Unavailable as a response.

server.timeout#

• <number> 超时（以毫秒为单位）。默认值：0（无超时）

  ¥<number> Timeout in milliseconds. Default: 0 (no timeout)

假定套接字超时之前不活动的毫秒数。

¥The number of milliseconds of inactivity before a socket is presumed to have timed out.

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

¥A value of 0 will disable the timeout behavior on incoming connections.

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

¥The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections.

server.keepAliveTimeout#

• <number> 超时（以毫秒为单位）。默认值：5000（5 秒）。

  ¥<number> Timeout in milliseconds. Default: 5000 (5 seconds).

在完成写入最后一个响应之后，在套接字将被销毁之前，服务器需要等待额外传入数据的不活动毫秒数。如果服务器在 keep-alive 超时触发之前收到新数据，则将重置常规的不活动超时，即 server.timeout。

¥The number of milliseconds of inactivity a server needs to wait for additional incoming data, after it has finished writing the last response, before a socket will be destroyed. If the server receives new data before the keep-alive timeout has fired, it will reset the regular inactivity timeout, i.e., server.timeout.

值 0 将禁用传入连接上的保持活动超时行为。值 0 使 http 服务器的行为类似于 8.0.0 之前的 Node.js 版本，后者没有保持活动超时。

¥A value of 0 will disable the keep-alive timeout behavior on incoming connections. A value of 0 makes the http server behave similarly to Node.js versions prior to 8.0.0, which did not have a keep-alive timeout.

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

¥The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections.

类：http.ServerResponse#

¥Class: http.ServerResponse

• 继承：<http.OutgoingMessage>

  ¥Extends: <http.OutgoingMessage>

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

¥This object is created internally by an HTTP server, not by the user. It is passed as the second parameter to the 'request' event.

事件：'close'#

¥Event: 'close'

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

¥Indicates that the response is completed, or its underlying connection was terminated prematurely (before the response completion).

事件：'finish'#

¥Event: 'finish'

发送响应时触发。更具体地说，当响应头和正文的最后一段已移交给操作系统以通过网络传输时，则将触发此事件。这并不意味着客户端已收到任何东西。

¥Emitted when the response has been sent. More specifically, this event is emitted when the last segment of the response headers and body have been handed off to the operating system for transmission over the network. It does not imply that the client has received anything yet.

response.addTrailers(headers)#

• headers <Object>

此方法向响应添加 HTTP 尾随标头（标头，但位于消息末尾）。

¥This method adds HTTP trailing headers (a header but at the end of the message) to the response.

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

¥Trailers will only be emitted if chunked encoding is used for the response; if it is not (e.g. if the request was HTTP/1.0), they will be silently discarded.

HTTP 要求发送 Trailer 标头以触发尾标，其值中包含标头字段列表。例如，

¥HTTP requires the Trailer header to be sent in order to emit trailers, with a list of the header fields in its value. E.g.,

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

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

¥Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

response.connection#

• <stream.Duplex>

参见 response.socket。

¥See response.socket.

response.cork()#

参见 writable.cork()。

¥See writable.cork().

response.end([data[, encoding]][, callback])#

• data <string> | <Buffer> | <Uint8Array>

• encoding <string>

• callback <Function>

• 返回：<this>

  ¥Returns: <this>

此方法向服务器触发信号，表明已发送所有响应标头和正文；该服务器应认为此消息已完成。response.end() 方法必须在每个响应上调用。

¥This method signals to the server that all of the response headers and body have been sent; that server should consider this message complete. The method, response.end(), MUST be called on each response.

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

¥If data is specified, it is similar in effect to calling response.write(data, encoding) followed by response.end(callback).

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

¥If callback is specified, it will be called when the response stream is finished.

response.finished#

• <boolean>

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

¥The response.finished property will be true if response.end() has been called.

response.flushHeaders()#

刷新响应头。也可以看看：request.flushHeaders()。

¥Flushes the response headers. See also: request.flushHeaders().

response.getHeader(name)#

• name <string>

• 返回：<any>

  ¥Returns: <any>

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

¥Reads out a header that's already been queued but not sent to the client. The name is case-insensitive. The type of the return value depends on the arguments provided to 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 is 'text/html'
const contentLength = response.getHeader('Content-Length');
// contentLength is of type number
const setCookie = response.getHeader('set-cookie');
// setCookie is of type string[] 拷贝

response.getHeaderNames()#

• 返回：<string[]>

  ¥Returns: <string[]>

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

¥Returns an array containing the unique names of the current outgoing headers. All header names are lowercase.

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

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

response.getHeaders()#

• 返回：<Object>

  ¥Returns: <Object>

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

¥Returns a shallow copy of the current outgoing headers. Since a shallow copy is used, array values may be mutated without additional calls to various header-related http module methods. The keys of the returned object are the header names and the values are the respective header values. All header names are lowercase.

response.getHeaders() 方法返回的对象不是原型继承自 JavaScript Object。这意味着 obj.toString()、obj.hasOwnProperty() 等典型的 Object 方法没有定义，将不起​​作用。

¥The object returned by the response.getHeaders() method does not prototypically inherit from the JavaScript Object. This means that typical Object methods such as obj.toString(), obj.hasOwnProperty(), and others are not defined and will not work.

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

• name <string>

• 返回：<boolean>

  ¥Returns: <boolean>

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

¥Returns true if the header identified by name is currently set in the outgoing headers. The header name matching is case-insensitive.

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

response.headersSent#

• <boolean>

布尔值（只读）。如果标头被发送，则为真，否则为假。

¥Boolean (read-only). True if headers were sent, false otherwise.

response.removeHeader(name)#

• name <string>

删除排队等待隐式发送的标头。

¥Removes a header that's queued for implicit sending.

response.removeHeader('Content-Encoding'); 拷贝

response.req#

• <http.IncomingMessage>

对原始的 HTTP request 对象的引用。

¥A reference to the original HTTP request object.

response.sendDate#

• <boolean>

如果为真，则 Date 标头将自动生成并在响应中发送，如果它尚未出现在标头中。默认为真。

¥When true, the Date header will be automatically generated and sent in the response if it is not already present in the headers. Defaults to true.

这应该只在测试时被禁用；HTTP 要求在响应中使用 Date 标头。

¥This should only be disabled for testing; HTTP requires the Date header in responses.

response.setHeader(name, value)#

• name <string>

• value <any>

• 返回：<http.ServerResponse>

  ¥Returns: <http.ServerResponse>

返回响应对象。

¥Returns the response object.

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

¥Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings here to send multiple headers with the same name. Non-string values will be stored without modification. Therefore, response.getHeader() may return non-string values. However, the non-string values will be converted to strings for network transmission. The same response object is returned to the caller, to enable call chaining.

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

或者

¥or

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

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

¥Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

当标头已使用 response.setHeader() 设置时，则它们将与任何传给 response.writeHead() 的标头合并，其中传给 response.writeHead() 的标头优先。

¥When headers have been set with response.setHeader(), they will be merged with any headers passed to response.writeHead(), with the headers passed to response.writeHead() given precedence.

// Returns 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()。

¥If response.writeHead() method is called and this method has not been called, it will directly write the supplied header values onto the network channel without caching internally, and the response.getHeader() on the header will not yield the expected result. If progressive population of headers is desired with potential future retrieval and modification, use response.setHeader() instead of response.writeHead().

response.setTimeout(msecs[, callback])#

• msecs <number>

• callback <Function>

• 返回：<http.ServerResponse>

  ¥Returns: <http.ServerResponse>

将套接字的超时值设置为 msecs。如果提供了回调，则将其添加为响应对象上 'timeout' 事件的监听器。

¥Sets the Socket's timeout value to msecs. If a callback is provided, then it is added as a listener on the 'timeout' event on the response object.

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

¥If no 'timeout' listener is added to the request, the response, or the server, then sockets are destroyed when they time out. If a handler is assigned to the request, the response, or the server's 'timeout' events, timed out sockets must be handled explicitly.

response.socket#

• <stream.Duplex>

对底层套接字的引用。通常用户不会想要访问这个属性。特别是，由于协议解析器附加到套接字的方式，套接字将不会触发 'readable' 事件。在 response.end() 之后，该属性为空。

¥Reference to the underlying socket. Usually users will not want to access this property. In particular, the socket will not emit 'readable' events because of how the protocol parser attaches to the socket. After response.end(), the property is nulled.

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);const http = require('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> 类（<stream.Duplex> 的子类）的实例，除非用户指定了 <net.Socket> 以外的套接字类型。

¥This property is guaranteed to be an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specified a socket type other than <net.Socket>.

response.statusCode#

• <number> 默认值：200

  ¥<number> Default: 200

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

¥When using implicit headers (not calling response.writeHead() explicitly), this property controls the status code that will be sent to the client when the headers get flushed.

response.statusCode = 404; 拷贝

响应头发送到客户端后，该属性表示发送出去的状态码。

¥After response header was sent to the client, this property indicates the status code which was sent out.

response.statusMessage#

• <string>

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

¥When using implicit headers (not calling response.writeHead() explicitly), this property controls the status message that will be sent to the client when the headers get flushed. If this is left as undefined then the standard message for the status code will be used.

response.statusMessage = 'Not found'; 拷贝

响应头发送到客户端后，该属性表示发送出去的状态消息。

¥After response header was sent to the client, this property indicates the status message which was sent out.

response.strictContentLength#

• <boolean> 默认值：false

  ¥<boolean> Default: false

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

¥If set to true, Node.js will check whether the Content-Length header value and the size of the body, in bytes, are equal. Mismatching the Content-Length header value will result in an Error being thrown, identified by code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.

response.uncork()#

参见 writable.uncork()。

¥See writable.uncork().

response.writableEnded#

• <boolean>

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

¥Is true after response.end() has been called. This property does not indicate whether the data has been flushed, for this use response.writableFinished instead.

response.writableFinished#

• <boolean>

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

¥Is true if all data has been flushed to the underlying system, immediately before the 'finish' event is emitted.

response.write(chunk[, encoding][, callback])#

• chunk <string> | <Buffer> | <Uint8Array>

• encoding <string> 默认值：'utf8'

  ¥encoding <string> Default: 'utf8'

• callback <Function>

• 返回：<boolean>

  ¥Returns: <boolean>

如果此方法被调用且 response.writeHead() 还没被调用，则会切换到隐式的标头模式并刷新隐式的标头。

¥If this method is called and response.writeHead() has not been called, it will switch to implicit header mode and flush the implicit headers.

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

¥This sends a chunk of the response body. This method may be called multiple times to provide successive parts of the body.

当请求方法或响应状态不支持内容时，不允许写入正文。如果尝试写入正文以获取 HEAD 请求或作为 204 或 304 响应的一部分，则会抛出代码为 ERR_HTTP_BODY_NOT_ALLOWED 的同步 Error。

¥Writing to the body is not allowed when the request method or response status do not support content. If an attempt is made to write to the body for a HEAD request or as part of a 204 or 304response, a synchronous Error with the code ERR_HTTP_BODY_NOT_ALLOWED is thrown.

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

¥chunk can be a string or a buffer. If chunk is a string, the second parameter specifies how to encode it into a byte stream. callback will be called when this chunk of data is flushed.

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

¥This is the raw HTTP body and has nothing to do with higher-level multi-part body encodings that may be used.

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

¥The first time response.write() is called, it will send the buffered header information and the first chunk of the body to the client. The second time response.write() is called, Node.js assumes data will be streamed, and sends the new data separately. That is, the response is buffered up to the first chunk of the body.

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

¥Returns true if the entire data was flushed successfully to the kernel buffer. Returns false if all or part of the data was queued in user memory. 'drain' will be emitted when the buffer is free again.

response.writeContinue()#

向客户端发送 HTTP/1.1 100 Continue 消息，指示应发送请求正文。请参阅 Server 上的 'checkContinue' 事件。

¥Sends an HTTP/1.1 100 Continue message to the client, indicating that the request body should be sent. See the 'checkContinue' event on Server.

response.writeEarlyHints(hints[, callback])#

• hints <Object>

• callback <Function>

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

¥Sends an HTTP/1.1 103 Early Hints message to the client with a Link header, indicating that the user agent can preload/preconnect the linked resources. The hints is an object containing the values of headers to be sent with early hints message. The optional callback argument will be called when the response message has been written.

示例

¥Example

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])#

• statusCode <number>

• statusMessage <string>

• headers <Object> | <Array>

• 返回：<http.ServerResponse>

  ¥Returns: <http.ServerResponse>

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

¥Sends a response header to the request. The status code is a 3-digit HTTP status code, like 404. The last argument, headers, are the response headers. Optionally one can give a human-readable statusMessage as the second argument.

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

¥headers may be an Array where the keys and values are in the same list. It is not a list of tuples. So, the even-numbered offsets are key values, and the odd-numbered offsets are the associated values. The array is in the same format as request.rawHeaders.

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

¥Returns a reference to the ServerResponse, so that calls can be chained.

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

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

¥This method must only be called once on a message and it must be called before response.end() is called.

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

¥If response.write() or response.end() are called before calling this, the implicit/mutable headers will be calculated and call this function.

当标头已使用 response.setHeader() 设置时，则它们将与任何传给 response.writeHead() 的标头合并，其中传给 response.writeHead() 的标头优先。

¥When headers have been set with response.setHeader(), they will be merged with any headers passed to response.writeHead(), with the headers passed to response.writeHead() given precedence.

如果调用了此方法，且还没调用 response.setHeader()，则会直接将提供的标头值写入网络通道且内部不缓存，在标头上 response.getHeader() 不会产生预期的结果。如果需要逐步填充标头并在未来进行潜在的检索和修改，则改用 response.setHeader()。

¥If this method is called and response.setHeader() has not been called, it will directly write the supplied header values onto the network channel without caching internally, and the response.getHeader() on the header will not yield the expected result. If progressive population of headers is desired with potential future retrieval and modification, use response.setHeader() instead.

// Returns 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');
}); 拷贝

Content-Length 以字节而不是字符读取。使用 Buffer.byteLength() 来确定正文的长度（以字节为单位）。Node.js 会检查 Content-Length 和已经传输的 body 的长度是否相等。

¥Content-Length is read in bytes, not characters. Use Buffer.byteLength() to determine the length of the body in bytes. Node.js will check whether Content-Length and the length of the body which has been transmitted are equal or not.

尝试设置包含无效字符的标头字段名称或值将导致抛出 [Error][Error]。

¥Attempting to set a header field name or value that contains invalid characters will result in a [Error][] being thrown.

response.writeProcessing()#

向客户端发送 HTTP/1.1 102 Processing 消息，表示应发送请求正文。

¥Sends a HTTP/1.1 102 Processing message to the client, indicating that the request body should be sent.

类：http.IncomingMessage#

¥Class: http.IncomingMessage

• 继承：<stream.Readable>

  ¥Extends: <stream.Readable>

IncomingMessage 对象由 http.Server 或 http.ClientRequest 创建，并分别作为第一个参数传给 'request' 和 'response' 事件。它可用于访问响应状态、标头和数据。

¥An IncomingMessage object is created by http.Server or http.ClientRequest and passed as the first argument to the 'request' and 'response' event respectively. It may be used to access response status, headers, and data.

不同于其 socket 的值是 <stream.Duplex> 的子类，IncomingMessage 本身继承了 <stream.Readable> 并被单独创建以解析和触发传入的 HTTP 标头和有效载荷，因为在保持活动的情况下底层套接字可能被多次重用。

¥Different from its socket value which is a subclass of <stream.Duplex>, the IncomingMessage itself extends <stream.Readable> and is created separately to parse and emit the incoming HTTP headers and payload, as the underlying socket may be reused multiple times in case of keep-alive.

事件：'aborted'#

¥Event: 'aborted'

当请求被中止时触发。

¥Emitted when the request has been aborted.

事件：'close'#

¥Event: 'close'

当请求完成时触发。

¥Emitted when the request has been completed.

message.aborted#

稳定性:0 - 已弃用。从 <stream.Readable> 检查 message.destroyed。

¥Stability: 0 - Deprecated. Check message.destroyed from <stream.Readable>.

• <boolean>

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

¥The message.aborted property will be true if the request has been aborted.

message.complete#

• <boolean>

如果已接收并成功解析完整的 HTTP 消息，则 message.complete 属性将为 true。

¥The message.complete property will be true if a complete HTTP message has been received and successfully parsed.

此属性作为一种确定客户端或服务器是否在连接终止之前完全传输消息的方法特别有用：

¥This property is particularly useful as a means of determining if a client or server fully transmitted a message before a connection was terminated:

const req = http.request({
  host: '127.0.0.1',
  port: 8080,
  method: 'POST',
}, (res) => {
  res.resume();
  res.on('end', () => {
    if (!res.complete)
      console.error(
        'The connection was terminated while the message was still being sent');
  });
}); 拷贝

message.connection#

message.socket 的别名。

¥Alias for message.socket.

message.destroy([error])#

• error <Error>

• 返回：<this>

  ¥Returns: <this>

在接收到 IncomingMessage 的套接字上调用 destroy()。如果提供了 error，则在套接字上触发 'error' 事件，并将 error 作为参数传给该事件的任何监听器。

¥Calls destroy() on the socket that received the IncomingMessage. If error is provided, an 'error' event is emitted on the socket and error is passed as an argument to any listeners on the event.

message.headers#

• <Object>

请求/响应头对象。

¥The request/response headers object.

标头名称和值的键值对。标头名称是小写的。

¥Key-value pairs of header names and values. Header names are lower-cased.

// Prints something like:
//
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers); 拷贝

原始标头中的重复项按以下方式处理，具体取决于标头名称：

¥Duplicates in raw headers are handled in the following ways, depending on the header name:

• 重复的 age、authorization、content-length、content-type、etag、expires、from、host、if-modified-since、if-unmodified-since、last-modified、location、max-forwards、proxy-authorization、referer、retry-after、server 或 user-agent 被丢弃。要允许合并上面列出的标头的重复值，请在 http.request() 和 http.createServer() 中使用选项 joinDuplicateHeaders。有关详细信息，请参阅 RFC 9110 第 5.3 节。

  ¥Duplicates of age, authorization, content-length, content-type, etag, expires, from, host, if-modified-since, if-unmodified-since, last-modified, location, max-forwards, proxy-authorization, referer, retry-after, server, or user-agent are discarded. To allow duplicate values of the headers listed above to be joined, use the option joinDuplicateHeaders in http.request() and http.createServer(). See RFC 9110 Section 5.3 for more information.

• set-cookie 始终是数组。重复项被添加到数组中。

  ¥set-cookie is always an array. Duplicates are added to the array.

• 对于重复的 cookie 标头，值使用 ; 连接。

  ¥For duplicate cookie headers, the values are joined together with ; .

• 对于所有其他标头，值使用 , 连接。

  ¥For all other headers, the values are joined together with , .

message.headersDistinct#

• <Object>

类似于 message.headers，但没有连接逻辑，并且值始终是字符串数组，即使对于仅收到一次的标头也是如此。

¥Similar to message.headers, but there is no join logic and the values are always arrays of strings, even for headers received just once.

// Prints something like:
//
// { 'user-agent': ['curl/7.22.0'],
//   host: ['127.0.0.1:8000'],
//   accept: ['*/*'] }
console.log(request.headersDistinct); 拷贝

message.httpVersion#

• <string>

在服务器请求的情况下，客户端发送的 HTTP 版本。在客户端响应的情况下，连接到服务器的 HTTP 版本。可能是 '1.1' 或 '1.0'。

¥In case of server request, the HTTP version sent by the client. In the case of client response, the HTTP version of the connected-to server. Probably either '1.1' or '1.0'.

message.httpVersionMajor 是第一个整数，message.httpVersionMinor 是第二个。

¥Also message.httpVersionMajor is the first integer and message.httpVersionMinor is the second.

message.method#

• <string>

仅对从 http.Server 获得的请求有效。

¥Only valid for request obtained from http.Server.

请求方法作为字符串。只读。示例：'GET', 'DELETE'.

¥The request method as a string. Read only. Examples: 'GET', 'DELETE'.

message.rawHeaders#

• <string[]>

原始请求/响应头完全按照收到的方式列出。

¥The raw request/response headers list exactly as they were received.

键和值在同一个列表中。它不是元组列表。因此，偶数偏移是键值，奇数偏移是关联的值。

¥The keys and values are in the same list. It is not a list of tuples. So, the even-numbered offsets are key values, and the odd-numbered offsets are the associated values.

标头名称不小写，重复项不合并。

¥Header names are not lowercased, and duplicates are not merged.

// Prints something like:
//
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders); 拷贝

message.rawTrailers#

• <string[]>

原始请求/响应尾标的键和值与收到的完全一样。仅在 'end' 事件中填充。

¥The raw request/response trailer keys and values exactly as they were received. Only populated at the 'end' event.

message.setTimeout(msecs[, callback])#

• msecs <number>

• callback <Function>

• 返回：<http.IncomingMessage>

  ¥Returns: <http.IncomingMessage>

调用 message.socket.setTimeout(msecs, callback)。

¥Calls message.socket.setTimeout(msecs, callback).

message.socket#

• <stream.Duplex>

与连接关联的 net.Socket 对象。

¥The net.Socket object associated with the connection.

使用 HTTPS 支持，使用 request.socket.getPeerCertificate() 获取客户端的身份验证详细信息。

¥With HTTPS support, use request.socket.getPeerCertificate() to obtain the client's authentication details.

此属性保证是 <net.Socket> 类（<stream.Duplex> 的子类）的实例，除非用户指定了 <net.Socket> 以外的套接字类型或内部为空。

¥This property is guaranteed to be an instance of the <net.Socket> class, a subclass of <stream.Duplex>, unless the user specified a socket type other than <net.Socket> or internally nulled.

message.statusCode#

• <number>

仅对从 http.ClientRequest 获得的响应有效。

¥Only valid for response obtained from http.ClientRequest.

3 位 HTTP 响应状态码。E.G.404。

¥The 3-digit HTTP response status code. E.G. 404.

message.statusMessage#

• <string>

仅对从 http.ClientRequest 获得的响应有效。

¥Only valid for response obtained from http.ClientRequest.

HTTP 响应状态消息（原因短语）。E.G.OK 或 Internal Server Error。

¥The HTTP response status message (reason phrase). E.G. OK or Internal Server Error.

message.trailers#

• <Object>

请求/响应尾标对象。仅在 'end' 事件中填充。

¥The request/response trailers object. Only populated at the 'end' event.

message.trailersDistinct#

• <Object>

类似于 message.trailers，但没有连接逻辑，并且值始终是字符串数组，即使对于仅收到一次的标头也是如此。仅在 'end' 事件中填充。

¥Similar to message.trailers, but there is no join logic and the values are always arrays of strings, even for headers received just once. Only populated at the 'end' event.

message.url#

• <string>

仅对从 http.Server 获得的请求有效。

¥Only valid for request obtained from http.Server.

请求的网址字符串。这仅包含实际 HTTP 请求中存在的网址。接受以下请求：

¥Request URL string. This contains only the URL that is present in the actual HTTP request. Take the following request:

GET /status?name=ryan HTTP/1.1
Accept: text/plain 拷贝

要将网址解析为它的部分：

¥To parse the URL into its parts:

new URL(request.url, `http://${request.headers.host}`); 拷贝

当 request.url 为 '/status?name=ryan' 且 request.headers.host 为 'localhost:3000' 时：

¥When request.url is '/status?name=ryan' and request.headers.host is 'localhost:3000':

$ node
> new URL(request.url, `http://${request.headers.host}`)
URL {
  href: 'http://localhost:3000/status?name=ryan',
  origin: 'http://localhost:3000',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'localhost:3000',
  hostname: 'localhost',
  port: '3000',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
} 拷贝

类：http.OutgoingMessage#

¥Class: http.OutgoingMessage

• 继承：<Stream>

  ¥Extends: <Stream>

该类作为 http.ClientRequest 和 http.ServerResponse 的父类。从 HTTP 事务的参与者的角度来看，这是抽象的传出消息。

¥This class serves as the parent class of http.ClientRequest and http.ServerResponse. It is an abstract outgoing message from the perspective of the participants of an HTTP transaction.

事件：'drain'#

¥Event: 'drain'

当消息的缓冲区再次空闲时触发。

¥Emitted when the buffer of the message is free again.

事件：'finish'#

¥Event: 'finish'

当传输成功完成时触发。

¥Emitted when the transmission is finished successfully.

事件：'prefinish'#

¥Event: 'prefinish'

调用 outgoingMessage.end() 后触发。触发事件时，所有数据都已处理，但不一定完全刷新。

¥Emitted after outgoingMessage.end() is called. When the event is emitted, all data has been processed but not necessarily completely flushed.

outgoingMessage.addTrailers(headers)#

• headers <Object>

添加 HTTP 尾标（标头，但在消息末尾）到消息。

¥Adds HTTP trailers (headers but at the end of the message) to the message.

仅当消息经过分块编码时才会触发标尾。如果没有，则块头将被默默丢弃。

¥Trailers will only be emitted if the message is chunked encoded. If not, the trailers will be silently discarded.

HTTP 要求发送 Trailer 标头以触发块头，其值中包含标头字段名称列表，例如

¥HTTP requires the Trailer header to be sent to emit trailers, with a list of header field names in its value, e.g.

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

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

¥Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

outgoingMessage.appendHeader(name, value)#

• name <string> 标头名称

  ¥name <string> Header name

• value <string> | <string[]> 标头值

  ¥value <string> | <string[]> Header value

• 返回：<this>

  ¥Returns: <this>

为标头对象附加单一个标头值。

¥Append a single header value for the header object.

如果值为数组，则相当于多次调用该方法。

¥If the value is an array, this is equivalent of calling this method multiple times.

如果标头没有先前的值，则这相当于调用 outgoingMessage.setHeader(name, value)。

¥If there were no previous value for the header, this is equivalent of calling outgoingMessage.setHeader(name, value).

根据创建客户端请求或服务器时 options.uniqueHeaders 的值，这将导致标头多次发送或单次发送，并使用 ; 连接值。

¥Depending of the value of options.uniqueHeaders when the client request or the server were created, this will end up in the header being sent multiple times or a single time with values joined using ; .

outgoingMessage.connection#

outgoingMessage.socket 的别名。

¥Alias of outgoingMessage.socket.

outgoingMessage.cork()#

参见 writable.cork()。

¥See writable.cork().

outgoingMessage.destroy([error])#

• error <Error> 可选，使用 error 事件触发的错误

  ¥error <Error> Optional, an error to emit with error event

• 返回：<this>

  ¥Returns: <this>

销毁消息。一旦套接字与消息关联并连接，则该套接字也将被销毁。

¥Destroys the message. Once a socket is associated with the message and is connected, that socket will be destroyed as well.

outgoingMessage.end(chunk[, encoding][, callback])#

• chunk <string> | <Buffer> | <Uint8Array>

• encoding <string> 可选，默认：utf8

  ¥encoding <string> Optional, Default: utf8

• callback <Function> 可选的

  ¥callback <Function> Optional

• 返回：<this>

  ¥Returns: <this>

完成传出消息。如果正文的任何部分未发送，则会将它们刷新到底层系统。如果消息被分块，则它将发送终止块 0\r\n\r\n，并发送块尾（如果有）。

¥Finishes the outgoing message. If any parts of the body are unsent, it will flush them to the underlying system. If the message is chunked, it will send the terminating chunk 0\r\n\r\n, and send the trailers (if any).

如果指定了 chunk，则相当于调用 outgoingMessage.write(chunk, encoding)，后跟 outgoingMessage.end(callback)。

¥If chunk is specified, it is equivalent to calling outgoingMessage.write(chunk, encoding), followed by outgoingMessage.end(callback).

如果提供了 callback，则在消息结束时调用（相当于 'finish' 事件的监听器）。

¥If callback is provided, it will be called when the message is finished (equivalent to a listener of the 'finish' event).

outgoingMessage.flushHeaders()#

刷新消息标头。

¥Flushes the message headers.

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

¥For efficiency reason, Node.js normally buffers the message headers until outgoingMessage.end() is called or the first chunk of message data is written. It then tries to pack the headers and data into a single TCP packet.

通常是需要的（节省了 TCP 往返），但不是在第一个数据没有被发送的时候，直到可能很晚。outgoingMessage.flushHeaders() 绕过优化并启动消息。

¥It is usually desired (it saves a TCP round-trip), but not when the first data is not sent until possibly much later. outgoingMessage.flushHeaders() bypasses the optimization and kickstarts the message.

outgoingMessage.getHeader(name)#

• name <string> 标头名称

  ¥name <string> Name of header

• 返回 <string> | <undefined>

  ¥Returns <string> | <undefined>

获取具有给定名称的 HTTP 标头的值。如果未设置该标头，则返回值为 undefined。

¥Gets the value of the HTTP header with the given name. If that header is not set, the returned value will be undefined.

outgoingMessage.getHeaderNames()#

• 返回 <string[]>

  ¥Returns <string[]>

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

¥Returns an array containing the unique names of the current outgoing headers. All names are lowercase.

outgoingMessage.getHeaders()#

• 返回：<Object>

  ¥Returns: <Object>

返回当前传出标头的浅拷贝。由于使用了浅拷贝，因此无需额外调用各种与标头相关的 HTTP 模块方法即可更改数组值。返回对象的键是标头名称，值是相应的标头值。所有标头名称均为小写。

¥Returns a shallow copy of the current outgoing headers. Since a shallow copy is used, array values may be mutated without additional calls to various header-related HTTP module methods. The keys of the returned object are the header names and the values are the respective header values. All header names are lowercase.

outgoingMessage.getHeaders() 方法返回的对象不是原型继承自 JavaScript Object。这意味着 obj.toString()、obj.hasOwnProperty() 等典型的 Object 方法没有定义，将不起​​作用。

¥The object returned by the outgoingMessage.getHeaders() method does not prototypically inherit from the JavaScript Object. This means that typical Object methods such as obj.toString(), obj.hasOwnProperty(), and others are not defined and will not work.

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

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

outgoingMessage.hasHeader(name)#

• name <string>

• 返回 <boolean>

  ¥Returns <boolean>

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

¥Returns true if the header identified by name is currently set in the outgoing headers. The header name is case-insensitive.

const hasContentType = outgoingMessage.hasHeader('content-type'); 拷贝

outgoingMessage.headersSent#

• <boolean>

只读。如果标头已发送，则为 true，否则为 false。

¥Read-only. true if the headers were sent, otherwise false.

outgoingMessage.pipe()#

覆盖继承自旧版的 Stream 类（http.OutgoingMessage 的父类）的 stream.pipe() 方法。

¥Overrides the stream.pipe() method inherited from the legacy Stream class which is the parent class of http.OutgoingMessage.

调用此方法将抛出 Error，因为 outgoingMessage 是只写流。

¥Calling this method will throw an Error because outgoingMessage is a write-only stream.

outgoingMessage.removeHeader(name)#

• name <string> 标头名称

  ¥name <string> Header name

删除排队等待隐式发送的标头。

¥Removes a header that is queued for implicit sending.

outgoingMessage.removeHeader('Content-Encoding'); 拷贝

outgoingMessage.setHeader(name, value)#

• name <string> 标头名称

  ¥name <string> Header name

• value <any> 标头值

  ¥value <any> Header value

• 返回：<this>

  ¥Returns: <this>

设置单个标头值。如果待发送标头中已经存在该标头，则替换其值。使用字符串数组发送多个同名标头。

¥Sets a single header value. If the header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings to send multiple headers with the same name.

outgoingMessage.setHeaders(headers)#

• headers <Headers> | <Map>

• 返回：<http.ServerResponse>

  ¥Returns: <http.ServerResponse>

返回响应对象。

¥Returns the response object.

为隐式标头设置多个标头值。headers 必须是 Headers 或 Map 的一个实例，如果一个标头已经存在于待发送的标头中，它的值将被替换。

¥Sets multiple header values for implicit headers. headers must be an instance of Headers or Map, if a header already exists in the to-be-sent headers, its value will be replaced.

const headers = new Headers({ foo: 'bar' });
response.setHeaders(headers); 拷贝

或者

¥or

const headers = new Map([['foo', 'bar']]);
res.setHeaders(headers); 拷贝

当标头已使用 outgoingMessage.setHeaders() 设置时，则它们将与任何传给 response.writeHead() 的标头合并，其中传给 response.writeHead() 的标头优先。

¥When headers have been set with outgoingMessage.setHeaders(), they will be merged with any headers passed to response.writeHead(), with the headers passed to response.writeHead() given precedence.

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  const headers = new Headers({ 'Content-Type': 'text/html' });
  res.setHeaders(headers);
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
}); 拷贝

outgoingMessage.setTimeout(msesc[, callback])#

• msesc <number>

• callback <Function> 发生超时时要调用的可选函数。与绑定到 timeout 事件相同。

  ¥callback <Function> Optional function to be called when a timeout occurs. Same as binding to the timeout event.

• 返回：<this>

  ¥Returns: <this>

一旦套接字与消息关联并连接，则 socket.setTimeout() 将被调用，msecs 作为第一个参数。

¥Once a socket is associated with the message and is connected, socket.setTimeout() will be called with msecs as the first parameter.

outgoingMessage.socket#

• <stream.Duplex>

对底层套接字的引用。通常，用户不会希望访问此属性。

¥Reference to the underlying socket. Usually, users will not want to access this property.

调用 outgoingMessage.end() 后，该属性将被清空。

¥After calling outgoingMessage.end(), this property will be nulled.

outgoingMessage.uncork()#

参见 writable.uncork()

¥See writable.uncork()

outgoingMessage.writableCorked#

• <number>

调用 outgoingMessage.cork() 的次数。

¥The number of times outgoingMessage.cork() has been called.

outgoingMessage.writableEnded#

• <boolean>

如果调用了 outgoingMessage.end()，则为 true。该属性不表示数据是否被刷新。为此目的，则改用 message.writableFinished。

¥Is true if outgoingMessage.end() has been called. This property does not indicate whether the data has been flushed. For that purpose, use message.writableFinished instead.

outgoingMessage.writableFinished#

• <boolean>

如果所有数据都已刷新到底层系统，则为 true。

¥Is true if all data has been flushed to the underlying system.

outgoingMessage.writableHighWaterMark#

• <number>

如果分配了底层套接字的 highWaterMark。否则，writable.write() 开始时的默认缓冲级别返回 false（16384）。

¥The highWaterMark of the underlying socket if assigned. Otherwise, the default buffer level when writable.write() starts returning false (16384).

outgoingMessage.writableLength#

• <number>

缓冲的字节数。

¥The number of buffered bytes.

outgoingMessage.writableObjectMode#

• <boolean>

始终为 false。

¥Always false.

outgoingMessage.write(chunk[, encoding][, callback])#

• chunk <string> | <Buffer> | <Uint8Array>

• encoding <string> 默认值：utf8

  ¥encoding <string> Default: utf8

• callback <Function>

• 返回 <boolean>

  ¥Returns <boolean>

发送一块正文。此方法可以被多次调用。

¥Sends a chunk of the body. This method can be called multiple times.

encoding 参数仅在 chunk 是字符串时才相关。默认为 'utf8'。

¥The encoding argument is only relevant when chunk is a string. Defaults to 'utf8'.

callback 参数是可选的，当此数据被刷新时将被调用。

¥The callback argument is optional and will be called when this chunk of data is flushed.

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

¥Returns true if the entire data was flushed successfully to the kernel buffer. Returns false if all or part of the data was queued in the user memory. The 'drain' event will be emitted when the buffer is free again.

http.METHODS#

• <string[]>

解析器支持的 HTTP 方法列表。

¥A list of the HTTP methods that are supported by the parser.

http.STATUS_CODES#

• <Object>

所有标准 HTTP 响应状态代码的集合，以及每个的简短描述。例如，http.STATUS_CODES[404] === 'Not Found'。

¥A collection of all the standard HTTP response status codes, and the short description of each. For example, http.STATUS_CODES[404] === 'Not Found'.

http.createServer([options][, requestListener])#

• options <Object>

  • connectionsCheckingInterval：以毫秒为单位设置间隔值，以检查不完整请求中的请求和标头超时。默认值：30000。

    ¥connectionsCheckingInterval: Sets the interval value in milliseconds to check for request and headers timeout in incomplete requests. Default: 30000.

  • headersTimeout：设置从客户端接收完整 HTTP 标头的超时值，以毫秒为单位。有关详细信息，请参阅 server.headersTimeout。默认值：60000。

    ¥headersTimeout: Sets the timeout value in milliseconds for receiving the complete HTTP headers from the client. See server.headersTimeout for more information. Default: 60000.

  • highWaterMark <number> 可选择覆盖所有 socket' readableHighWaterMark 和 writableHighWaterMark。这会影响 IncomingMessage 和 ServerResponse 的 highWaterMark 属性。默认值：参见 stream.getDefaultHighWaterMark()。

    ¥highWaterMark <number> Optionally overrides all sockets' readableHighWaterMark and writableHighWaterMark. This affects highWaterMark property of both IncomingMessage and ServerResponse. Default: See stream.getDefaultHighWaterMark().

  • insecureHTTPParser <boolean> 使用不安全的 HTTP 解析器，当为 true 时接受无效的 HTTP 标头。应避免使用不安全的解析器。有关详细信息，请参阅 --insecure-http-parser。默认值：false。

    ¥insecureHTTPParser <boolean> Use an insecure HTTP parser that accepts invalid HTTP headers when true. Using the insecure parser should be avoided. See --insecure-http-parser for more information. Default: false.

  • IncomingMessage <http.IncomingMessage> 指定要使用的 IncomingMessage 类。用于扩展原始的 IncomingMessage。默认值：IncomingMessage。

    ¥IncomingMessage <http.IncomingMessage> Specifies the IncomingMessage class to be used. Useful for extending the original IncomingMessage. Default: IncomingMessage.

  • joinDuplicateHeaders <boolean> 它使用 , 连接请求中多个标头的字段行值，而不是丢弃重复项。有关详细信息，请参阅 message.headers。默认值：false。

    ¥joinDuplicateHeaders <boolean> It joins the field line values of multiple headers in a request with , instead of discarding the duplicates. See message.headers for more information. Default: false.

  • keepAlive <boolean> 如果设置为 true，则在收到新的传入连接后立即启用套接字上的保持活动功能，与 [socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)] 中的操作类似。默认值：false。

    ¥keepAlive <boolean> If set to true, it enables keep-alive functionality on the socket immediately after a new incoming connection is received, similarly on what is done in [socket.setKeepAlive([enable][, initialDelay])][socket.setKeepAlive(enable, initialDelay)]. Default: false.

  • keepAliveInitialDelay <number> 如果设置为正数，则它会设置在空闲套接字上发送第一个保持活跃探测之前的初始延迟。默认值：0。

    ¥keepAliveInitialDelay <number> If set to a positive number, it sets the initial delay before the first keepalive probe is sent on an idle socket. Default: 0.

  • requestTimeout：设置从客户端接收整个请求的超时值（以毫秒为单位）。有关详细信息，请参阅 server.requestTimeout。默认值：300000。

    ¥requestTimeout: Sets the timeout value in milliseconds for receiving the entire request from the client. See server.requestTimeout for more information. Default: 300000.

  • ServerResponse <http.ServerResponse> 指定要使用的 ServerResponse 类。用于扩展原始的 ServerResponse。默认值：ServerResponse。

    ¥ServerResponse <http.ServerResponse> Specifies the ServerResponse class to be used. Useful for extending the original ServerResponse. Default: ServerResponse.

  • uniqueHeaders <Array> 只应发送一次的响应标头列表。如果标头的值是数组，则子项将使用 ; 连接。

    ¥uniqueHeaders <Array> A list of response headers that should be sent only once. If the header's value is an array, the items will be joined using ; .

• requestListener <Function>

• 返回：<http.Server>

  ¥Returns: <http.Server>

返回 http.Server 的新实例。

¥Returns a new instance of http.Server.

requestListener 是自动添加到 'request' 事件的函数。

¥The requestListener is a function which is automatically added to the 'request' event.

import http from 'node:http';

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

server.listen(8000);const http = require('node:http');

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

server.listen(8000);拷贝

import http from 'node:http';

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);const http = require('node:http');

// Create a local server to receive data from
const server = http.createServer();

// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
  }));
});

server.listen(8000);拷贝

http.get(options[, callback])#

http.get(url[, options][, callback])#

• url <string> | <URL>

• options <Object> 接受与 http.request() 相同的 options，方法默认设置为 GET。

  ¥options <Object> Accepts the same options as http.request(), with the method set to GET by default.

• callback <Function>

• 返回：<http.ClientRequest>

  ¥Returns: <http.ClientRequest>

由于大多数请求是没有正文的 GET 请求，因此 Node.js 提供了这个便捷的方法。该方法与 http.request() 唯一的区别是它默认设置方法为 GET 并自动调用 req.end()。因为 http.ClientRequest 章节所述的原因，回调必须注意消费响应数据。

¥Since most requests are GET requests without bodies, Node.js provides this convenience method. The only difference between this method and http.request() is that it sets the method to GET by default and calls req.end() automatically. The callback must take care to consume the response data for reasons stated in http.ClientRequest section.

callback 使用单个参数（http.IncomingMessage 的实例）调用。

¥The callback is invoked with a single argument that is an instance of http.IncomingMessage.

获取 JSON 的示例：

¥JSON fetching example:

http.get('http://localhost:8000/', (res) => {
  const { statusCode } = res;
  const contentType = res.headers['content-type'];

  let error;
  // Any 2xx status code signals a successful response but
  // here we're only checking for 200.
  if (statusCode !== 200) {
    error = new Error('Request Failed.\n' +
                      `Status Code: ${statusCode}`);
  } else if (!/^application\/json/.test(contentType)) {
    error = new Error('Invalid content-type.\n' +
                      `Expected application/json but received ${contentType}`);
  }
  if (error) {
    console.error(error.message);
    // Consume response data to free up memory
    res.resume();
    return;
  }

  res.setEncoding('utf8');
  let rawData = '';
  res.on('data', (chunk) => { rawData += chunk; });
  res.on('end', () => {
    try {
      const parsedData = JSON.parse(rawData);
      console.log(parsedData);
    } catch (e) {
      console.error(e.message);
    }
  });
}).on('error', (e) => {
  console.error(`Got error: ${e.message}`);
});

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

server.listen(8000); 拷贝

http.globalAgent#

• <http.Agent>

Agent 的全局实例，用作所有 HTTP 客户端请求的默认值。

¥Global instance of Agent which is used as the default for all HTTP client requests.

http.maxHeaderSize#

• <number>

只读属性，指定 HTTP 标头的最大允许大小（以字节为单位）。默认为 16 KiB。可使用 --max-http-header-size 命令行选项进行配置。

¥Read-only property specifying the maximum allowed size of HTTP headers in bytes. Defaults to 16 KiB. Configurable using the --max-http-header-size CLI option.

这可以通过传入 maxHeaderSize 选项为服务器和客户端请求覆盖。

¥This can be overridden for servers and client requests by passing the maxHeaderSize option.

http.request(options[, callback])#

http.request(url[, options][, callback])#

• url <string> | <URL>

• options <Object>

  • agent <http.Agent> | <boolean> 控制 Agent 的行为。可能的值：

    ¥agent <http.Agent> | <boolean> Controls Agent behavior. Possible values:

    • undefined（默认）：使用 http.globalAgent 作为主机和端口。

      ¥undefined (default): use http.globalAgent for this host and port.

    • Agent 对象：显式使用传入的 Agent。

      ¥Agent object: explicitly use the passed in Agent.

    • false：使用具有默认值的新 Agent。

      ¥false: causes a new Agent with default values to be used.

  • auth <string> 用于计算授权标头的基本身份验证 ('user:password')。

    ¥auth <string> Basic authentication ('user:password') to compute an Authorization header.

  • createConnection <Function> 当不使用 agent 选项时，生成用于请求的套接字/流的函数。这可用于避免创建自定义 Agent 类只是为了覆盖默认的 createConnection 函数。有关详细信息，请参阅 agent.createConnection()。任何 Duplex 流都是有效的返回值。

    ¥createConnection <Function> A function that produces a socket/stream to use for the request when the agent option is not used. This can be used to avoid creating a custom Agent class just to override the default createConnection function. See agent.createConnection() for more details. Any Duplex stream is a valid return value.

  • defaultPort <number> 协议的默认端口。默认值：如果使用 Agent，则为 agent.defaultPort，否则为 undefined。

    ¥defaultPort <number> Default port for the protocol. Default: agent.defaultPort if an Agent is used, else undefined.

  • family <number> 解析 host 或 hostname 时使用的 IP 地址族。有效值为 4 或 6。当未指定时，则将使用 IP v4 和 v6。

    ¥family <number> IP address family to use when resolving host or hostname. Valid values are 4 or 6. When unspecified, both IP v4 and v6 will be used.

  • headers <Object> 包含请求头的对象。

    ¥headers <Object> An object containing request headers.

  • hints <number> 可选 dns.lookup() 提示。

    ¥hints <number> Optional dns.lookup() hints.

  • host <string> 要向其触发请求的服务器的域名或 IP 地址。默认值：'localhost'。

    ¥host <string> A domain name or IP address of the server to issue the request to. Default: 'localhost'.

  • hostname <string> host 的别名。为了支持 url.parse()，如果同时指定了 host 和 hostname，则将使用 hostname。

    ¥hostname <string> Alias for host. To support url.parse(), hostname will be used if both host and hostname are specified.

  • insecureHTTPParser <boolean> 使用不安全的 HTTP 解析器，当为 true 时接受无效的 HTTP 标头。应避免使用不安全的解析器。有关详细信息，请参阅 --insecure-http-parser。默认值：false

    ¥insecureHTTPParser <boolean> Use an insecure HTTP parser that accepts invalid HTTP headers when true. Using the insecure parser should be avoided. See --insecure-http-parser for more information. Default: false

  • joinDuplicateHeaders <boolean> 它使用 , 连接请求中多个标头的字段行值，而不是丢弃重复项。有关详细信息，请参阅 message.headers。默认值：false。

    ¥joinDuplicateHeaders <boolean> It joins the field line values of multiple headers in a request with , instead of discarding the duplicates. See message.headers for more information. Default: false.

  • localAddress <string> 用于绑定网络连接的本地接口。

    ¥localAddress <string> Local interface to bind for network connections.

  • localPort <number> 连接的本地端口。

    ¥localPort <number> Local port to connect from.

  • lookup <Function> 自定义查找函数。默认值：dns.lookup()。

    ¥lookup <Function> Custom lookup function. Default: dns.lookup().

  • maxHeaderSize <number> 对于从服务器接收到的响应，可选择覆盖 --max-http-header-size 的值（响应标头的最大长度，以字节为单位）。默认值：16384 (16 KiB)。

    ¥maxHeaderSize <number> Optionally overrides the value of --max-http-header-size (the maximum length of response headers in bytes) for responses received from the server. Default: 16384 (16 KiB).

  • method <string> 指定 HTTP 请求方法的字符串。默认值：'GET'。

    ¥method <string> A string specifying the HTTP request method. Default: 'GET'.

  • path <string> 请求的路径。应包括查询字符串（如果有）。E.G.'/index.html?page=12'。当请求路径包含非法字符时抛出异常。目前，只有空格被拒绝，但将来可能会改变。默认值：'/'。

    ¥path <string> Request path. Should include query string if any. E.G. '/index.html?page=12'. An exception is thrown when the request path contains illegal characters. Currently, only spaces are rejected but that may change in the future. Default: '/'.

  • port <number> 远程服务器的端口。默认值：如果设置则为 defaultPort，否则为 80。

    ¥port <number> Port of remote server. Default: defaultPort if set, else 80.

  • protocol <string> 要使用的协议。默认值：'http:'。

    ¥protocol <string> Protocol to use. Default: 'http:'.

  • setHost <boolean> :指定是否自动添加 Host 标头。默认为 true。

    ¥setHost <boolean>: Specifies whether or not to automatically add the Host header. Defaults to true.

  • signal <AbortSignal> :可用于中止正在进行的请求的中止信号。

    ¥signal <AbortSignal>: An AbortSignal that may be used to abort an ongoing request.

  • socketPath <string> Unix 域套接字。如果指定了 host 或 port 之一，则不能使用，因为它们指定了 TCP 套接字。

    ¥socketPath <string> Unix domain socket. Cannot be used if one of host or port is specified, as those specify a TCP Socket.

  • timeout <number> :以毫秒为单位指定套接字超时的数字。这将在连接套接字之前设置超时。

    ¥timeout <number>: A number specifying the socket timeout in milliseconds. This will set the timeout before the socket is connected.

  • uniqueHeaders <Array> 只应发送一次的请求标头列表。如果标头的值是数组，则子项将使用 ; 连接。

    ¥uniqueHeaders <Array> A list of request headers that should be sent only once. If the header's value is an array, the items will be joined using ; .

• callback <Function>

• 返回：<http.ClientRequest>

  ¥Returns: <http.ClientRequest>