Node.js v18.18.2 文档

类：http.Agent#

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

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

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

最好在不再使用时destroy() 实例Agent ，因为未使用的套接字会消耗操作系统资源。

当套接字发出'close'事件或'agentRemove'事件时，套接字将从代理中删除。当打算长时间保持一个 HTTP 请求打开而不将其保留在代理中时，可以执行如下操作：

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

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

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

new Agent([options])#

• options <Object>要在代理上设置的可配置选项集。可以有以下字段：
  • keepAlive <boolean>即使没有未完成的请求也保留套接字，以便它们可以用于将来的请求，而无需重新建立 TCP 连接。不要与 Connection 标头的keep-alive 值混淆。 使用代理时，始终发送Connection: keep-alive标头，除非 显式指定Connection标头或keepAlive和maxSockets 选项分别设置为false和Infinity，在这种情况下 将使用Connection: close 。默认值： false。
  • keepAliveMsecs <number>使用keepAlive选项时，指定 TCP Keep-Alive 数据包的初始延迟。当 keepAlive选项为false或undefined时被忽略。默认值： 1000。
  • maxSockets <number>每个主机允许的最大套接字数。如果同一主机打开多个并发连接，每个请求将使用新的套接字，直到达到maxSockets值。如果主机尝试打开的连接多于maxSockets，则额外的请求将进入待处理请求队列，并在现有连接终止时进入事件连接状态。这可确保在任何时间点 最多有来自给定主机的maxSockets 个事件连接。默认值： Infinity。
  • maxTotalSockets <number>所有主机允许的最大套接字总数。每个请求都将使用一个新的套接字，直到达到最大值。 默认值： Infinity。
  • maxFreeSockets <number>每个主机在空闲状态下保持打开状态的最大套接字数。仅当keepAlive设置为true时相关。 默认值： 256。
  • scheduling <string>选择下一个要使用的空闲套接字时应用的调度策略。它可以是'fifo'或'lifo'。两种调度策略之间的主要区别在于，'lifo' 选择最近使用的套接字，而'fifo'选择最近最少使用的套接字。如果每秒请求率较低，'lifo'调度将降低选择可能因不事件而被服务器关闭的套接字的风险。如果每秒请求率很高，'fifo'调度将最大化打开套接字的数量，而'lifo'调度将使其尽可能低。 默认值： 'lifo'。
  • timeout <number>套接字超时（以毫秒为单位）。这将在创建套接字时设置超时。

还支持socket.connect()中的 options 。

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

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

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

agent.createConnection(options[, callback])#

• options <Object>包含连接详细信息的选项。检查 net.createConnection()选项的格式
• callback <Function>接收创建的套接字的回调函数
• 返回：<流.Duplex>

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

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

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

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

callback的签名为(err, stream)。

agent.keepSocketAlive(socket)#

• socket <流.Duplex>

当socket与请求分离并且可以由 Agent保留时调用。默认行为是：

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

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

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

agent.reuseSocket(socket, request)#

• socket <流.Duplex>
• request <http.ClientRequest>

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

socket.ref(); copy

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

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

agent.destroy()#

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

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

agent.freeSockets#

• <对象>

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

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

agent.getName([options])#

• options <Object>一组提供名称生成信息的选项
  • host <string>向其发出请求的服务器的域名或 IP 地址
  • port <number>远程服务器端口
  • localAddress <string>发出请求时绑定网络连接的本地接口
  • family <integer>如果不等于undefined ，则必须为 4 或 6 。
• 返回：<字符串>

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

agent.maxFreeSockets#

• <数字>

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

agent.maxSockets#

• <数字>

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

agent.maxTotalSockets#

• <数字>

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

agent.requests#

• <对象>

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

agent.sockets#

• <对象>

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

类：http.ClientRequest#

• 扩展：<http.OutgoingMessage>

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

要获取响应，请将'response'的侦听器添加到请求对象。 收到响应标头后，将从请求对象发出'response' 。'response'事件使用一个参数执行，该参数是http.IncomingMessage的实例。

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

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

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

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

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

事件：'abort'#

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

事件：'close'#

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

事件：'connect'#

• response <http.IncomingMessage>
• socket <流.Duplex>
• head <缓冲区>

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

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

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

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

事件：'continue'#

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

事件：'finish'#

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

事件：'information'#

• info <对象>
  • httpVersion <字符串>
  • httpVersionMajor <整数>
  • httpVersionMinor <整数>
  • statusCode <整数>
  • statusMessage <字符串>
  • headers <对象>
  • rawHeaders <字符串[]>

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

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}`);
}); copy

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

事件：'response'#

• response <http.IncomingMessage>

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

事件：'socket'#

• socket <流.Duplex>

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

事件：'timeout'#

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

另请参阅：request.setTimeout()。

事件：'upgrade'#

• response <http.IncomingMessage>
• socket <流.Duplex>
• head <缓冲区>

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

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

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

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

request.abort()#

将请求标记为中止。调用此函数将导致响应中的剩余数据被丢弃，并且套接字被破坏。

request.aborted#

• <布尔值>

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

request.connection#

• <流.双工>

请参阅request.socket。

request.cork()#

请参阅writable.cork()。

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

• data <字符串> | <缓冲区> | <Uint8Array>
• encoding <字符串>
• callback <函数>
• 返回：<此>

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

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

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

request.destroy([error])#

• error <Error>可选，随'error'事件发出的错误。
• 返回：<此>

销毁请求。（可选）发出'error'事件，并发出'close'事件。调用此函数将导致响应中的剩余数据被丢弃，并且套接字被破坏。

请参阅writable.destroy()了解更多详情。

request.destroyed#

• <布尔值>

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

请参阅writable.destroyed了解更多详情。

request.finished#

• <布尔值>

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

request.flushHeaders()#

刷新请求标头。

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

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

request.getHeader(name)#

• name <字符串>
• 返回：<任意>

读出请求的标头。该名称不区分大小写。返回值的类型取决于提供给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[] copy

request.getHeaderNames()#

• 返回：<字符串[]>

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

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

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

request.getHeaders()#

• 返回：<对象>

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

request.getHeaders()方法返回的对象在原型上并非 继承自 JavaScript Object。这意味着典型的 Object方法（例如obj.toString()、obj.hasOwnProperty()和其他方法）未定义并且无法工作。

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

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

request.getRawHeaderNames()#

• 返回：<字符串[]>

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

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

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

request.hasHeader(name)#

• name <字符串>
• 返回：<布尔值>

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

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

request.maxHeadersCount#

• <数字> 默认值： 2000

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

request.path#

• <字符串>请求路径。

request.method#

• <string>请求方法。

request.host#

• <string>请求主机。

request.protocol#

• <string>请求协议。

request.removeHeader(name)#

• name <字符串>

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

request.removeHeader('Content-Type'); copy

request.reusedSocket#

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

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

const 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 copy

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

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

request.setHeader(name, value)#

• name <字符串>
• value <任意>

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

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

或者

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

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

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

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

request.setNoDelay([noDelay])#

• noDelay <布尔值>

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

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

• enable <布尔值>
• initialDelay <数字>

一旦将套接字分配给此请求并连接， 就会调用socket.setKeepAlive() 。

request.setTimeout(timeout[, callback])#

• timeout <number>请求超时前的毫秒数。
• callback <Function>发生超时时调用的可选函数。与绑定到'timeout'事件相同。
• 返回：<http.ClientRequest>

一旦将套接字分配给此请求并连接， 就会调用socket.setTimeout() 。

request.socket#

• <流.双工>

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

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

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

request.uncork()#

请参阅writable.uncork()。

request.writableEnded#

• <布尔值>

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

request.writableFinished#

• <布尔值>

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

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

• chunk <字符串> | <缓冲区> | <Uint8Array>
• encoding <字符串>
• callback <函数>
• 返回：<布尔值>

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

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

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

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

当使用空字符串或缓冲区调用write函数时，它不执行任何操作并等待更多输入。

类：http.Server#

• 扩展：<net.Server>

事件：'checkContinue'#

• request <http.IncomingMessage>
• response <http.ServerResponse>

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

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

当发出并处理此事件时，将不会发出'request'事件。

事件：'checkExpectation'#

• request <http.IncomingMessage>
• response <http.ServerResponse>

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

发出并处理此事件时，将不会发出'request'事件。

事件：'clientError'#

• exception <错误>
• socket <流.Duplex>

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

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

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

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

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

当'clientError'事件发生时，没有request或response 对象，因此发送的任何 HTTP 响应（包括响应标头和负载）都 必须直接写入socket对象。必须注意确保响应是格式正确的 HTTP 响应消息。

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

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

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

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

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

事件：'close'#

服务器关闭时发出。

事件：'connect'#

• request <http.IncomingMessage> HTTP 请求的参数，就像在'request'事件中一样
• socket <stream.Duplex>服务器和客户端之间的网络套接字
• head <Buffer>隧道流的第一个数据包（可能为空）

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

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

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

事件：'connection'#

• socket <流.Duplex>

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

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

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

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

事件：'dropRequest'#

• request <http.IncomingMessage> HTTP 请求的参数，就像在'request'事件中一样
• socket <stream.Duplex>服务器和客户端之间的网络套接字

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

事件：'request'#

• request <http.IncomingMessage>
• response <http.ServerResponse>

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

事件：'upgrade'#

• request <http.IncomingMessage> HTTP 请求的参数，就像在'request'事件中一样
• socket <stream.Duplex>服务器和客户端之间的网络套接字
• head <Buffer>升级后的流的第一个数据包（可能为空）

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

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

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

server.close([callback])#

• callback <函数>

停止服务器接受新连接。请参阅net.Server.close()。

server.closeAllConnections()#

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

server.closeIdleConnections()#

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

server.headersTimeout#

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

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

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

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

server.listen()#

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

server.listening#

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

server.maxHeadersCount#

• <数字> 默认值： 2000

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

server.requestTimeout#

• <数字> 默认值： 300000

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

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

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

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

• msecs <number> 默认值： 0（无超时）
• callback <函数>
• 返回：<http.Server>

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

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

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

server.maxRequestsPerSocket#

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

在关闭保持事件连接之前套接字可以处理的最大请求数。

值为0将禁用该限制。

当达到限制时，它将把Connection标头值设置为close，但不会真正关闭连接，达到限制后发送的后续请求将得到503 Service Unavailable作为回应。

server.timeout#

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

假定套接字超时之前不事件的毫秒数。

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

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

server.keepAliveTimeout#

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

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

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

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

类：http.ServerResponse#

• 扩展：<http.OutgoingMessage>

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

事件：'close'#

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

事件：'finish'#

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

response.addTrailers(headers)#

• headers <对象>

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

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

HTTP 需要发送Trailer标头才能发出预告片，其值中包含标头字段列表。例如，

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

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

response.connection#

• <流.双工>

请参阅response.socket。

response.cork()#

请参阅writable.cork()。

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

• data <字符串> | <缓冲区> | <Uint8Array>
• encoding <字符串>
• callback <函数>
• 返回：<此>

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

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

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

response.finished#

• <布尔值>

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

response.flushHeaders()#

刷新响应标头。另请参阅：request.flushHeaders()。

response.getHeader(name)#

• name <字符串>
• 返回：<任意>

读出已排队但未发送到客户端的标头。该名称不区分大小写。返回值的类型取决于提供给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[] copy

response.getHeaderNames()#

• 返回：<字符串[]>

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

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

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

response.getHeaders()#

• 返回：<对象>

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

response.getHeaders()方法返回的对象在原型上并非 继承自 JavaScript Object。这意味着典型的 Object方法（例如obj.toString()、obj.hasOwnProperty()和其他方法）未定义并且无法工作。

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

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

response.hasHeader(name)#

• name <字符串>
• 返回：<布尔值>

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

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

response.headersSent#

• <布尔值>

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

response.removeHeader(name)#

• name <字符串>

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

response.removeHeader('Content-Encoding'); copy

response.req#

• <http.IncomingMessage>

对原始 HTTP request对象的引用。

response.sendDate#

• <布尔值>

如果为 true，则将自动生成 Date 标头并在响应中发送（如果标头中尚不存在）。默认为 true。

仅应在测试时禁用此功能；HTTP 要求响应中包含日期标头。

response.setHeader(name, value)#

• name <字符串>
• value <任意>
• 返回：<http.ServerResponse>

返回响应对象。

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

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

或者

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

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

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

// 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');
}); copy

如果调用了response.writeHead()方法并且尚未调用该方法，它将直接将提供的标头值写入网络通道，而不进行内部缓存，并且标头上的 response.getHeader()不会产生预期的结果。如果需要渐进式填充标头以及将来可能的检索和修改，请使用 response.setHeader()而不是response.writeHead()。

response.setTimeout(msecs[, callback])#

• msecs <数字>
• callback <函数>
• 返回：<http.ServerResponse>

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

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

response.socket#

• <流.双工>

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

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

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

response.statusCode#

• <数字> 默认值： 200

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

response.statusCode = 404; copy

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

response.statusMessage#

• <字符串>

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

response.statusMessage = 'Not found'; copy

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

response.strictContentLength#

• <布尔值> 默认值： false

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

response.uncork()#

请参阅writable.uncork()。

response.writableEnded#

• <布尔值>

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

response.writableFinished#

• <布尔值>

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

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

• chunk <字符串> | <缓冲区> | <Uint8Array>
• encoding <字符串> 默认值： 'utf8'
• callback <函数>
• 返回：<布尔值>

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

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

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

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

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

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

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

response.writeContinue()#

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

response.writeEarlyHints(hints[, callback])#

• hints <对象>
• callback <函数>

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

例子

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

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

const earlyHintsCallback = () => console.log('early hints message sent');
response.writeEarlyHints({
  'link': earlyHintsLinks,
}, earlyHintsCallback); copy

response.writeHead(statusCode[, statusMessage][, headers])#

• statusCode <数字>
• statusMessage <字符串>
• headers <对象> | <数组>
• 返回：<http.ServerResponse>

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

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

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

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

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

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

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

如果调用此方法并且尚未调用response.setHeader() ，它将直接将提供的标头值写入网络通道，而不进行内部缓存，并且标头上的response.getHeader()不会产生预期结果。如果需要渐进式填充标头以及将来可能的检索和修改，请改用 response.setHeader()。

// 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');
}); copy

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

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

response.writeProcessing()#

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

类：http.IncomingMessage#

• 扩展：<stream.Readable>

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

与作为<stream.Duplex>子类的socket值不同， IncomingMessage本身扩展<stream.Readable>并单独创建以解析和发出传入的 HTTP 标头，并有效负载，因为在保持事件状态的情况下，底层套接字可能会被重复使用多次。

事件：'aborted'#

当请求被中止时发出。

事件：'close'#

请求完成后发出。

message.aborted#

• <布尔值>

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

message.complete#

• <布尔值>

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

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

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');
  });
}); copy

message.connection#

message.socket的别名。

message.destroy([error])#

• error <错误>
• 返回：<此>

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

message.headers#

• <对象>

请求/响应标头对象。

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

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

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

• 重复的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 节。
• set-cookie始终是一个数组。重复项将添加到数组中。
• 对于重复的cookie标头，这些值将与; 连接在一起。
• 对于所有其他标头，这些值通过, 连接在一起。

message.headersDistinct#

• <对象>

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

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

message.httpVersion#

• <字符串>

如果是服务器请求，则为客户端发送的 HTTP 版本。如果是客户端响应，则为所连接服务器的 HTTP 版本。可能是'1.1'或'1.0'。

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

message.method#

• <字符串>

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

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

message.rawHeaders#

• <字符串[]>

原始请求/响应标头的列表与收到时完全相同。

键和值位于同一列表中。它不是元组列表。因此，偶数编号的偏移量是键值，奇数编号的偏移量是关联值。

标头名称不是小写的，并且不会合并重复项。

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

message.rawTrailers#

• <字符串[]>

原始请求/响应尾部键和值与收到时完全相同。仅在'end'事件中填充。

message.setTimeout(msecs[, callback])#

• msecs <数字>
• callback <函数>
• 返回：<http.IncomingMessage>

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

message.socket#

• <流.双工>

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

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

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

message.statusCode#

• <数字>

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

3 位 HTTP 响应状态代码。EG 404。

message.statusMessage#

• <字符串>

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

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

message.trailers#

• <对象>

请求/响应预告片对象。仅在'end'事件中填充。

message.trailersDistinct#

• <对象>

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

message.url#

• <字符串>

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

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

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

要将 URL 解析为各个部分：

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

当request.url为'/status?name=ryan'且request.headers.host为 '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: ''
} copy

类：http.OutgoingMessage#

• 扩展：<流>

此类充当http.ClientRequest 和http.ServerResponse的父类。从 HTTP 事务参与者的角度来看，它是一个抽象的传出消息。

事件：'drain'#

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

事件：'finish'#

传输成功完成时发出。

事件：'prefinish'#

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

outgoingMessage.addTrailers(headers)#

• headers <对象>

将 HTTP 尾部（标头，但位于消息末尾）添加到消息中。

仅当消息经过分块编码时才会发出预告片。如果没有，预告片将被默默丢弃。

HTTP 需要发送Trailer标头来发出预告片，其值中包含标头字段名称列表，例如

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

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

outgoingMessage.appendHeader(name, value)#

• name <string>标头名称
• value <字符串> | <string[]>标头值
• 返回：<此>

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

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

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

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

outgoingMessage.connection#

outgoingMessage.socket的别名。

outgoingMessage.cork()#

请参阅writable.cork()。

outgoingMessage.destroy([error])#

• error <Error>可选，随error事件发出的错误
• 返回：<此>

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

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

• chunk <字符串> | <缓冲区> | <Uint8Array>
• encoding <string>可选，默认：utf8
• callback <函数>可选
• 返回：<此>

完成外发消息。如果身体的任何部分未发送，它会将它们刷新到底层系统。如果消息被分块，它将发送终止块0\r\n\r\n，并发送预告片（如果有）。

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

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

outgoingMessage.flushHeaders()#

刷新消息标头。

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

通常需要这样做（它可以节省 TCP 往返），但当第一个数据可能要等到很晚之后才发送时，则不需要这样做。outgoingMessage.flushHeaders() 绕过优化并启动消息。

outgoingMessage.getHeader(name)#

• name <string>标头名称
• 返回<字符串> | <未定义>

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

outgoingMessage.getHeaderNames()#

• 返回<字符串[]>

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

outgoingMessage.getHeaders()#

• 返回：<对象>

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

outgoingMessage.getHeaders()方法返回的对象在原型上并非继承自 JavaScript Object。这意味着典型的Object方法（例如obj.toString()、obj.hasOwnProperty()和其他方法）未定义并且无法工作。

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'] } copy

outgoingMessage.hasHeader(name)#

• name <字符串>
• 返回<布尔值>

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

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

outgoingMessage.headersSent#

• <布尔值>

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

outgoingMessage.pipe()#

重写从旧版Stream类继承的stream.pipe()方法，该类是http.OutgoingMessage的父类。

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

outgoingMessage.removeHeader(name)#

• name <string>标头名称

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

outgoingMessage.removeHeader('Content-Encoding'); copy

outgoingMessage.setHeader(name, value)#

• name <string>标头名称
• value <any>标头值
• 返回：<此>

设置单个标头值。如果要发送的标头中已存在该标头，则其值将被替换。使用字符串数组发送多个具有相同名称的标头。

outgoingMessage.setHeaders(headers)#

• headers <标头> | <地图>
• 返回：<http.ServerResponse>

返回响应对象。

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

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

或者

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

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

// 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');
}); copy

outgoingMessage.setTimeout(msesc[, callback])#

• msesc <数字>
• callback <Function>发生超时时调用的可选函数。与绑定到timeout事件相同。
• 返回：<此>

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

outgoingMessage.socket#

• <流.双工>

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

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

outgoingMessage.uncork()#

请参阅writable.uncork()

outgoingMessage.writableCorked#

• <数字>

调用outgoingMessage.cork()的次数。

outgoingMessage.writableEnded#

• <布尔值>

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

outgoingMessage.writableFinished#

• <布尔值>

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

outgoingMessage.writableHighWaterMark#

• <数字>

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

outgoingMessage.writableLength#

• <数字>

缓冲的字节数。

outgoingMessage.writableObjectMode#

• <布尔值>

始终false。

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

• chunk <字符串> | <缓冲区> | <Uint8Array>
• encoding <字符串> 默认：utf8
• callback <函数>
• 返回<布尔值>

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

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

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

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

http.METHODS#

• <字符串[]>

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

http.STATUS_CODES#

• <对象>

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

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

• options <对象>

  • connectionsCheckingInterval：设置以毫秒为单位的间隔值，以检查不完整请求中的请求和标头超时。 默认值： 30000。
  • headersTimeout：设置从客户端接收完整 HTTP 标头的超时值（以毫秒为单位）。请参阅server.headersTimeout了解更多信息。 默认值： 60000。
  • highWaterMark <number>（可选）覆盖所有socket的 readableHighWaterMark和writableHighWaterMark。这会影响 IncomingMessage和ServerResponse的 highWaterMark 属性。 默认值：请参阅stream.getDefaultHighWaterMark()。
  • insecureHTTPParser <boolean>使用不安全的 HTTP 解析器，在true时接受无效的 HTTP 标头。应避免使用不安全的解析器。请参阅--insecure-http-parser了解更多信息。 默认值： false。
  • IncomingMessage <http.IncomingMessage>指定 要使用的IncomingMessage类。对于扩展原始的IncomingMessage很有用。 默认值： IncomingMessage。
  • joinDuplicateHeaders <boolean>它使用, 连接请求中多个标头的字段行值，而不是丢弃重复项。请参阅message.headers了解更多信息。 默认值： false。
  • keepAlive <boolean>如果设置为true，则在收到新的传入连接后立即启用套接字上的保持事件功能，类似于 [ socket.setKeepAlive([enable][, initialDelay]) ][ socket.setKeepAlive(enable, initialDelay) ]。 默认值： false。
  • keepAliveInitialDelay <number>如果设置为正数，则设置在空闲套接字上发送第一个保活探测之​​前的初始延迟。 默认值： 0。
  • requestTimeout：设置从客户端接收整个请求的超时值（以毫秒为单位）。请参阅server.requestTimeout了解更多信息。 默认值： 300000。
  • ServerResponse <http.ServerResponse>指定要使用的ServerResponse类。对于扩展原始的ServerResponse很有用。默认值： ServerResponse。
  • uniqueHeaders <Array>只应发送一次的响应标头列表。如果标头的值是数组，则将使用; 连接项目。

• requestListener <函数>

• 返回：<http.Server>

返回http.Server的新实例。

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

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

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

http.get(options[, callback])#

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

• url <字符串> | <网址>
• options <Object>接受与 http.request()相同的options，方法默认设置为 GET。
• callback <函数>
• 返回：<http.ClientRequest>

由于大多数请求都是没有主体的 GET 请求，Node.js 提供了这种便捷的方法。此方法与http.request()唯一的区别 在于，它默认将方法设置为 GET 并自动调用req.end() 。由于http.ClientRequest部分中所述的原因，回调必须注意使用响应数据。

callback使用单个参数调用，该参数是 http.IncomingMessage的实例。

JSON 获取示例：

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

http.globalAgent#

• <http.代理>

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

http.maxHeaderSize#

• <数字>

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

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

http.request(options[, callback])#

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

• url <字符串> | <网址>
• options <对象>
  • agent <http.Agent> | <boolean>控制Agent行为。可能的值：
    • undefined（默认）：为此主机和端口使用http.globalAgent 。
    • Agent对象：显式使用传入的Agent。
    • false ：导致使用具有默认值的新Agent 。
  • auth <string>基本身份验证 ( 'user:password' ) 用于计算授权标头。
  • createConnection <Function>当不使用agent选项时，生成用于请求的套接字/流的函数。这可用于避免创建自定义Agent类只是为了覆盖默认的 createConnection函数。请参阅agent.createConnection()了解更多详情。任何Duplex流都是有效的返回值。
  • defaultPort <number>协议的默认端口。默认值： 如果使用Agent，则为agent.defaultPort ，否则为undefined。
  • family <number>解析host或 hostname时使用的 IP 地址系列。有效值为4或6。如果未指定，则将使用 IPv4 和 v6。
  • headers <Object>包含请求标头的对象。
  • hints <number>可选的dns.lookup()提示。
  • host <string>发出请求的服务器的域名或 IP 地址。默认值： 'localhost'。
  • hostname <string> host的别名。为了支持url.parse()， 如果同时指定了host和hostname将使用 hostname 。
  • insecureHTTPParser <boolean>使用不安全的 HTTP 解析器，在true时接受无效的 HTTP 标头。应避免使用不安全的解析器。请参阅--insecure-http-parser了解更多信息。 默认值： false
  • joinDuplicateHeaders <boolean>它使用, 连接请求中多个标头的字段行值，而不是丢弃重复项。请参阅message.headers了解更多信息。 默认值： false。
  • localAddress <string>用于绑定网络连接的本地接口。
  • localPort <number>要连接的本地端口。
  • lookup <Function>自定义查找函数。默认值： dns.lookup()。
  • maxHeaderSize <number>可以选择覆盖从服务器收到的响应的--max-http-header-size值 （响应标头的最大长度，以字节为单位）。 默认值： 16384 (16 KiB)。
  • method <string>指定 HTTP 请求方法的字符串。默认值： 'GET'。
  • path <string>请求路径。应包含查询字符串（如果有）。EG '/index.html?page=12'。当请求路径包含非法字符时抛出异常。目前，仅拒绝空格，但将来可能会改变。默认值： '/'。
  • port <number>远程服务器的端口。默认值： 如果设置为defaultPort ，否则为80。
  • protocol <string>要使用的协议。默认值： 'http:'。
  • setHost <boolean>：指定是否自动添加 Host标头。默认为true。
  • signal <AbortSignal>：可用于中止正在进行的请求的 AbortSignal。
  • socketPath <string> Unix 域套接字。如果指定了host 或port之一，则无法使用，因为它们指定了 TCP 套接字。
  • timeout <number>：指定套接字超时的数字（以毫秒为单位）。这将在连接套接字之前设置超时。
  • uniqueHeaders <Array>只应发送一次的请求标头列表。如果标头的值是数组，则将使用; 连接项目。
• callback <函数>
• 返回：<http.ClientRequest>

还支持socket.connect()中的options 。

Node.js 为每个服务器维护多个连接来发出 HTTP 请求。这一功能允许人们透明地发出请求。

url可以是字符串或URL对象。如果url是字符串，则会自动使用new URL()进行解析。如果是URL 对象，则会自动转换为普通的options对象。

如果同时指定了url和options，则对象将被合并，且 options属性优先。

可选的callback参数将添加为'response'事件的一次性侦听器。

http.request()返回http.ClientRequest类的实例 。ClientRequest实例是一个可写流。如果需要通过 POST 请求上传文件，则写入ClientRequest对象。

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

const postData = JSON.stringify({
  'msg': 'Hello World!',
});

const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
  },
};

const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

// Write data to request body
req.write(postData);
req.end(); copy

在示例中调用了req.end() 。对于http.request()，必须始终调用req.end()来表示请求结束 - 即使没有数据写入请求正文。

如果请求期间遇到任何错误（无论是 DNS 解析错误、TCP 级别错误还是实际的 HTTP 解析错误），都会在返回的请求对象上发出'error'事件。与所有'error'事件一样，如果没有注册侦听器，则会引发错误。

有一些特殊的标题需要注意。

• 发送“Connection: keep-alive”将通知 Node.js 与服务器的连接应保持到下一个请求为止。

• 发送“Content-Length”标头将禁用默认的分块编码。

• 发送“Expect”标头将立即发送请求标头。通常，在发送“Expect: 100-continue”时，应设置'continue'事件的超时和侦听器。有关详细信息，请参阅 RFC 2616 第 8.2.3 节。

• 发送授权标头将覆盖使用auth选项来计算基本身份验证。

使用URL作为options 的示例：

const options = new URL('http://abc:[email protected]');

const req = http.request(options, (res) => {
  // ...
}); copy

在成功的请求中，将按以下顺序发出以下事件：

• 'socket'
• 'response'
  • 在res对象上'data'任意次数（如果响应正文为空，例如在大多数重定向中，则根本不会发出 'data' ）
  • res对象上的'end'
• 'close'

如果发生连接错误，将发出以下事件：

• 'socket'
• 'error'
• 'close'

如果在收到响应之前连接过早关闭，则将按以下顺序发出以下事件：

• 'socket'
• 'error'出现错误，消息为'Error: socket hang up'，代码为 'ECONNRESET'
• 'close'

如果在收到响应后连接过早关闭，则将按以下顺序发出以下事件：

• 'socket'
• 'response'
  • 在res对象上'data'任意次数
• （此处连接已关闭）
• res对象上的'aborted'
• res对象上的'error'出现错误，消息为 'Error: aborted'，代码为'ECONNRESET'
• 'close'
• res对象上的'close'

如果在分配套接字之前调用req.destroy() ，则将按以下顺序发出以下事件：

• （此处调用了req.destroy() ）
• 'error'出现错误，消息为'Error: socket hang up'且代码 为'ECONNRESET' ，或者调用req.destroy()时出现错误
• 'close'

如果在连接成功之前调用req.destroy() ，则将按以下顺序发出以下事件：

• 'socket'
• （此处调用了req.destroy() ）
• 'error'出现错误，消息为'Error: socket hang up'且代码 为'ECONNRESET' ，或者调用req.destroy()时出现错误
• 'close'

如果在收到响应后调用req.destroy() ，则将按以下顺序发出以下事件：

• 'socket'
• 'response'
  • 在res对象上'data'任意次数
• （此处调用了req.destroy() ）
• res对象上的'aborted'
• res对象上的'error'出现消息'Error: aborted' 和代码'ECONNRESET' 的错误，或者req.destroy()被称为
• 'close'
• res对象上的'close'

如果在分配套接字之前调用req.abort() ，则将按以下顺序发出以下事件：

• （此处调用了req.abort() ）
• 'abort'
• 'close'

如果在连接成功之前调用req.abort() ，则将按以下顺序发出以下事件：

• 'socket'
• （此处调用了req.abort() ）
• 'abort'
• 'error'出现错误，消息为'Error: socket hang up'，代码为 'ECONNRESET'
• 'close'

如果在收到响应后调用req.abort() ，则将按以下顺序发出以下事件：

• 'socket'
• 'response'
  • 在res对象上'data'任意次数
• （此处调用了req.abort() ）
• 'abort'
• res对象上的'aborted'
• res对象上的'error'出现错误，消息为 'Error: aborted'，代码为'ECONNRESET'。
• 'close'
• res对象上的'close'

设置timeout选项或使用setTimeout()函数不会中止请求，也不会执行除添加'timeout'事件之外的任何操作。

传递AbortSignal，然后对相应的 AbortController调用abort() 的行为与对请求调用.destroy()的行为相同。具体来说，将发出'error'事件，并带有消息'AbortError: The operation was aborted'、代码'ABORT_ERR' 和cause 的错误，如果假如。

http.validateHeaderName(name[, label])#

• name <字符串>
• label <string>错误消息的标签。默认值： 'Header name'。

对提供的name执行低级验证，这些验证在调用res.setHeader(name, value)时完成 。

将非法值作为name传递将导致抛出TypeError ，由code: 'ERR_INVALID_HTTP_TOKEN'标识。

在将标头传递给 HTTP 请求或响应之前，不必使用此方法。HTTP 模块将自动验证此类标头。例子：

例子：

const { validateHeaderName } = require('node:http');

try {
  validateHeaderName('');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message); // --> 'Header name must be a valid HTTP token [""]'
} copy

http.validateHeaderValue(name, value)#

• name <字符串>
• value <任意>

对提供的value执行低级验证，这些验证在调用res.setHeader(name, value)时完成 。

将非法值作为value传递将导致抛出TypeError 。

• 未定义值错误由code: 'ERR_HTTP_INVALID_HEADER_VALUE'标识。
• 无效值字符错误由code: 'ERR_INVALID_CHAR'标识。

在将标头传递给 HTTP 请求或响应之前，不必使用此方法。HTTP 模块将自动验证此类标头。

例子：

const { validateHeaderValue } = require('node:http');

try {
  validateHeaderValue('x-my-header', undefined);
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_HTTP_INVALID_HEADER_VALUE'); // --> true
  console.error(err.message); // --> 'Invalid value "undefined" for header "x-my-header"'
}

try {
  validateHeaderValue('x-my-header', 'oʊmɪɡə');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code === 'ERR_INVALID_CHAR'); // --> true
  console.error(err.message); // --> 'Invalid character in header content ["x-my-header"]'
} copy

http.setMaxIdleHTTPParsers(max)#

• max <数字> 默认值： 1000。

设置空闲 HTTP 解析器的最大数量。