Node.js v24.0.0 文档

Http2Session 和 sockets#

每个 Http2Session 实例在创建时都与一个 net.Socket 或 tls.TLSSocket 相关联。 当 Socket 或 Http2Session 被销毁时，两者都将被销毁。

由于 HTTP/2 协议施加的特定序列化和处理要求，不建议用户代码从绑定到 Http2Session 的 Socket 实例读取数据或向其写入数据。 这样做可能会使 HTTP/2 会话进入不确定状态，从而导致会话和套接字变得不可用。

一旦 Socket 已绑定到 Http2Session，用户代码应仅依赖于 Http2Session 的 API。

事件: 'close'#

'close' 事件在 Http2Session 被销毁后发出。 它的监听器不期望任何参数。

事件: 'connect'#

• session <Http2Session>
• socket <net.Socket>

'connect' 事件在 Http2Session 成功连接到远程对等方并且可以开始通信后发出。

用户代码通常不会直接监听此事件。

事件: 'error'#

• error <Error>

当在处理 Http2Session 期间发生错误时，会触发 'error' 事件。

事件: 'frameError'#

• type <integer> 帧类型。
• code <integer> 错误代码。
• id <integer> 流 ID (如果帧与流无关，则为 0)。

当尝试在会话上发送帧时发生错误时，会触发 'frameError' 事件。 如果无法发送的帧与特定的 Http2Stream 相关联，则会尝试在 Http2Stream 上触发 'frameError' 事件。

如果 'frameError' 事件与流相关联，则该流将在 'frameError' 事件之后立即关闭并销毁。 如果该事件与流无关，则 Http2Session 将在 'frameError' 事件之后立即关闭。

事件: 'goaway'#

• errorCode <number> GOAWAY 帧中指定的 HTTP/2 错误代码。
• lastStreamID <number> 远程对等方成功处理的最后一个流的 ID (如果未指定 ID，则为 0)。
• opaqueData <Buffer> 如果 GOAWAY 帧中包含额外的 opaque 数据，则将传递一个包含该数据的 Buffer 实例。

当收到 GOAWAY 帧时，会触发 'goaway' 事件。

当触发 'goaway' 事件时，Http2Session 实例将自动关闭。

事件: 'localSettings'#

• settings <HTTP/2 设置对象> 收到的 SETTINGS 帧的副本。

当收到确认 SETTINGS 帧时，会触发 'localSettings' 事件。

当使用 http2session.settings() 提交新设置时，修改后的设置只有在触发 'localSettings' 事件后才会生效。

session.settings({ enablePush: false });

session.on('localSettings', (settings) => {
  /* Use the new settings */
}); copy

事件: 'ping'#

• payload <Buffer> PING 帧的 8 字节负载

每当从连接的对等方收到 PING 帧时，就会触发 'ping' 事件。

事件: 'remoteSettings'#

• settings <HTTP/2 设置对象> 收到的 SETTINGS 帧的副本。

当从连接的对等方收到新的 SETTINGS 帧时，会触发 'remoteSettings' 事件。

session.on('remoteSettings', (settings) => {
  /* Use the new settings */
}); copy

事件: 'stream'#

• stream <Http2Stream> 对流的引用
• headers <HTTP/2 标头对象> 描述标头的对象
• flags <number> 关联的数字标志
• rawHeaders <Array> 包含原始标头名称及其相应值的数组。

当创建新的 Http2Stream 时，会触发 'stream' 事件。

session.on('stream', (stream, headers, flags) => {
  const method = headers[':method'];
  const path = headers[':path'];
  // ...
  stream.respond({
    ':status': 200,
    'content-type': 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
}); copy

在服务器端，用户代码通常不会直接监听此事件，而是会为 net.Server 或 tls.Server 实例触发的 'stream' 事件注册一个处理程序，这些实例由 http2.createServer() 和 http2.createSecureServer() 返回，如下例所示

import { createServer } from 'node:http2';

// Create an unencrypted HTTP/2 server
const server = createServer();

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.on('error', (error) => console.error(error));
  stream.end('<h1>Hello World</h1>');
});

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

// Create an unencrypted HTTP/2 server
const server = http2.createServer();

server.on('stream', (stream, headers) => {
  stream.respond({
    'content-type': 'text/html; charset=utf-8',
    ':status': 200,
  });
  stream.on('error', (error) => console.error(error));
  stream.end('<h1>Hello World</h1>');
});

server.listen(8000);copy

即使 HTTP/2 流和网络套接字不是 1:1 对应关系，网络错误也会销毁每个单独的流，并且必须在流级别处理，如上所示。

事件: 'timeout'#

在使用 http2session.setTimeout() 方法为此 Http2Session 设置超时时间后，如果在配置的毫秒数之后 Http2Session 上没有活动，则会触发 'timeout' 事件。 它的侦听器不期望任何参数。

session.setTimeout(2000);
session.on('timeout', () => { /* .. */ }); copy

http2session.alpnProtocol#

• <string> | <undefined>

如果 Http2Session 尚未连接到套接字，则值为 undefined；如果 Http2Session 未连接到 TLSSocket，则值为 h2c；否则将返回连接的 TLSSocket 自身的 alpnProtocol 属性的值。

http2session.close([callback])#

• callback <Function>

优雅地关闭 Http2Session，允许任何现有的流自行完成，并防止创建新的 Http2Stream 实例。 一旦关闭，如果没有打开的 Http2Stream 实例，可能会调用 http2session.destroy()。

如果指定，则将 callback 函数注册为 'close' 事件的处理程序。

http2session.closed#

• <boolean>

如果此 Http2Session 实例已关闭，则为 true，否则为 false。

http2session.connecting#

• <boolean>

如果此 Http2Session 实例仍在连接，则为 true，在触发 connect 事件和/或调用 http2.connect 回调之前，将设置为 false。

http2session.destroy([error][, code])#

• error <Error> 如果由于错误而销毁 Http2Session，则为 Error 对象。
• code <number> 在最终的 GOAWAY 帧中发送的 HTTP/2 错误代码。 如果未指定，并且 error 未定义，则默认值为 INTERNAL_ERROR，否则默认为 NO_ERROR。

立即终止 Http2Session 和关联的 net.Socket 或 tls.TLSSocket。

一旦销毁，Http2Session 将触发 'close' 事件。 如果 error 未定义，则会在 'close' 事件之前立即触发 'error' 事件。

如果与 Http2Session 关联的仍有任何打开的 Http2Streams，这些流也将被销毁。

http2session.destroyed#

• <boolean>

如果此 Http2Session 实例已被销毁并且不再使用，则为 true，否则为 false。

http2session.encrypted#

• <boolean> | <undefined>

如果 Http2Session 会话套接字尚未连接，则值为 undefined；如果 Http2Session 通过 TLSSocket 连接，则值为 true；如果 Http2Session 连接到任何其他类型的套接字或流，则值为 false。

http2session.goaway([code[, lastStreamID[, opaqueData]]])#

• code <number> HTTP/2 错误代码
• lastStreamID <number> 上次处理的 Http2Stream 的数字 ID
• opaqueData <Buffer> | <TypedArray> | <DataView> TypedArray 或 DataView 实例，包含要在 GOAWAY 帧中携带的附加数据。

将 GOAWAY 帧传输到连接的对等方，而不关闭 Http2Session。

http2session.localSettings#

• <HTTP/2 设置对象>

一个无原型的对象，描述了此 Http2Session 的当前本地设置。 本地设置是此 Http2Session 实例的本地设置。

http2session.originSet#

• <string[]> | <undefined>

如果 Http2Session 连接到 TLSSocket，则 originSet 属性将返回一个 Array，其中包含 Http2Session 可能被认为是权威的来源。

originSet 属性仅在使用安全的 TLS 连接时可用。

http2session.pendingSettingsAck#

• <boolean>

指示 Http2Session 当前是否正在等待对发送的 SETTINGS 帧的确认。 调用 http2session.settings() 方法后，将为 true。 一旦所有发送的 SETTINGS 帧都得到确认，将为 false。

http2session.ping([payload, ]callback)#

• payload <Buffer> | <TypedArray> | <DataView> 可选的 ping 负载。
• callback <Function>
• 返回: <boolean>

向连接的 HTTP/2 对等方发送 PING 帧。 必须提供 callback 函数。 如果发送了 PING，该方法将返回 true，否则返回 false。

未完成（未确认）的 ping 的最大数量由 maxOutstandingPings 配置选项确定。 默认最大值为 10。

如果提供了 payload，则 payload 必须是 Buffer、TypedArray 或 DataView，其中包含 8 字节的数据，这些数据将与 PING 一起传输，并与 ping 确认一起返回。

回调函数将被调用，并带有三个参数：一个错误参数，如果 PING 成功确认，则该参数将为 null；一个 duration 参数，报告自发送 ping 到接收到确认之间经过的毫秒数；以及一个 Buffer，其中包含 8 字节的 PING payload。

session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
  if (!err) {
    console.log(`Ping acknowledged in ${duration} milliseconds`);
    console.log(`With payload '${payload.toString()}'`);
  }
}); copy

如果未指定 payload 参数，则默认的 payload 将是 64 位时间戳（小端），标记 PING 持续时间的开始。

http2session.ref()#

在 Http2Session 实例的底层 net.Socket 上调用 ref()。

http2session.remoteSettings#

• <HTTP/2 设置对象>

一个无原型对象，描述此 Http2Session 的当前远程设置。 远程设置由 *已连接的* HTTP/2 对等方设置。

http2session.setLocalWindowSize(windowSize)#

• windowSize <number>

设置本地端点的窗口大小。 windowSize 是要设置的总窗口大小，而不是增量。

import { createServer } from 'node:http2';

const server = createServer();
const expectedWindowSize = 2 ** 20;
server.on('session', (session) => {

  // Set local window size to be 2 ** 20
  session.setLocalWindowSize(expectedWindowSize);
});const http2 = require('node:http2');

const server = http2.createServer();
const expectedWindowSize = 2 ** 20;
server.on('session', (session) => {

  // Set local window size to be 2 ** 20
  session.setLocalWindowSize(expectedWindowSize);
});copy

对于 http2 客户端，正确的事件是 'connect' 或 'remoteSettings'。

http2session.setTimeout(msecs, callback)#

• msecs <number>
• callback <Function>

用于设置一个回调函数，该函数在 msecs 毫秒后 Http2Session 上没有活动时被调用。 给定的 callback 被注册为 'timeout' 事件的监听器。

http2session.socket#

• <net.Socket> | <tls.TLSSocket>

返回一个 Proxy 对象，该对象充当 net.Socket (或 tls.TLSSocket)，但限制了可用方法为可安全用于 HTTP/2 的方法。

destroy、emit、end、pause、read、resume 和 write 将抛出一个代码为 ERR_HTTP2_NO_SOCKET_MANIPULATION 的错误。 有关更多信息，请参见 Http2Session 和 Sockets。

setTimeout 方法将在此 Http2Session 上调用。

所有其他交互将直接路由到套接字。

http2session.state#

提供有关 Http2Session 当前状态的各种信息。

• <Object>
  • effectiveLocalWindowSize <number> Http2Session 的当前本地（接收）流量控制窗口大小。
  • effectiveRecvDataLength <number> 自上次流量控制 WINDOW_UPDATE 以来收到的当前字节数。
  • nextStreamID <number> 下次由此 Http2Session 创建新的 Http2Stream 时要使用的数字标识符。
  • localWindowSize <number> 远程对等方可以在不接收 WINDOW_UPDATE 的情况下发送的字节数。
  • lastProcStreamID <number> 最近接收到 HEADERS 或 DATA 帧的 Http2Stream 的数字 ID。
  • remoteWindowSize <number> 此 Http2Session 可以在不接收 WINDOW_UPDATE 的情况下发送的字节数。
  • outboundQueueSize <number> 此 Http2Session 的出站队列中当前帧的数量。
  • deflateDynamicTableSize <number> 出站标头压缩状态表的当前大小（以字节为单位）。
  • inflateDynamicTableSize <number> 入站标头压缩状态表的当前大小（以字节为单位）。

一个对象，描述此 Http2Session 的当前状态。

http2session.settings([settings][, callback])#

• settings <HTTP/2 Settings Object>
• callback <Function> 会话连接后调用的回调函数，如果会话已连接，则立即调用。
  • err <Error> | <null>
  • settings <HTTP/2 Settings Object> 更新后的 settings 对象。
  • duration <integer>

更新此 Http2Session 的当前本地设置，并向连接的 HTTP/2 对等方发送新的 SETTINGS 帧。

一旦调用，http2session.pendingSettingsAck 属性将为 true，当会话正在等待远程对等方确认新设置时。

在接收到 SETTINGS 确认并发出 'localSettings' 事件之前，新设置不会生效。 可以在仍在等待确认时发送多个 SETTINGS 帧。

http2session.type#

• <number>

如果此 Http2Session 实例是服务器，则 http2session.type 将等于 http2.constants.NGHTTP2_SESSION_SERVER；如果该实例是客户端，则 http2session.type 将等于 http2.constants.NGHTTP2_SESSION_CLIENT。

http2session.unref()#

在 Http2Session 实例的底层 net.Socket 上调用 unref()。

serverhttp2session.altsvc(alt, originOrStream)#

• alt <string> 备用服务配置的描述，由 RFC 7838 定义。
• originOrStream <number> | <string> | <URL> | <Object> 指定原点的 URL 字符串（或具有 origin 属性的 Object），或者活动 Http2Stream 的数字标识符，如 http2stream.id 属性给出的。

向连接的客户端提交 ALTSVC 帧（如 RFC 7838 定义的）。

import { createServer } from 'node:http2';

const server = createServer();
server.on('session', (session) => {
  // Set altsvc for origin https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80');
});

server.on('stream', (stream) => {
  // Set altsvc for a specific stream
  stream.session.altsvc('h2=":8000"', stream.id);
});const http2 = require('node:http2');

const server = http2.createServer();
server.on('session', (session) => {
  // Set altsvc for origin https://example.org:80
  session.altsvc('h2=":8000"', 'https://example.org:80');
});

server.on('stream', (stream) => {
  // Set altsvc for a specific stream
  stream.session.altsvc('h2=":8000"', stream.id);
});copy

使用特定流 ID 发送 ALTSVC 帧表明备用服务与给定 Http2Stream 的原点相关联。

alt 和原点字符串 *必须* 仅包含 ASCII 字节，并且严格解释为 ASCII 字节序列。 可以传递特殊值 'clear' 以清除给定域的任何先前设置的备用服务。

当为 originOrStream 参数传递字符串时，它将被解析为 URL，并且将导出原点。 例如，HTTP URL 'https://example.org/foo/bar' 的原点是 ASCII 字符串 'https://example.org'。 如果给定的字符串无法解析为 URL 或无法导出有效的原点，则将抛出错误。

一个 URL 对象，或任何具有 origin 属性的对象，可以作为 originOrStream 传递，在这种情况下，将使用 origin 属性的值。 origin 属性的值 *必须* 是正确序列化的 ASCII 原点。

指定备用服务#

alt 参数的格式由 RFC 7838 严格定义，作为一个 ASCII 字符串，其中包含与特定主机和端口关联的以逗号分隔的“备用”协议列表。

例如，值 'h2="example.org:81"' 表示 HTTP/2 协议在 TCP/IP 端口 81 上的主机 'example.org' 上可用。 主机和端口 *必须* 包含在引号 (") 字符内。

可以指定多个备选项，例如：'h2="example.org:81", h2=":82"'。

协议标识符（示例中的 'h2'）可以是任何有效的 ALPN 协议 ID。

这些值的语法未由 Node.js 实现验证，并且按用户提供或从对等方接收的方式传递。

serverhttp2session.origin(...origins)#

• origins <string> | <URL> | <Object> 作为单独参数传递的一个或多个 URL 字符串。

向连接的客户端提交 ORIGIN 帧（如 RFC 8336 定义的），以通知服务器能够提供权威响应的原点集。

import { createSecureServer } from 'node:http2';
const options = getSecureOptionsSomehow();
const server = createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});
server.on('session', (session) => {
  session.origin('https://example.com', 'https://example.org');
});const http2 = require('node:http2');
const options = getSecureOptionsSomehow();
const server = http2.createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});
server.on('session', (session) => {
  session.origin('https://example.com', 'https://example.org');
});copy

当字符串作为 origin 传递时，它将被解析为 URL，并且将导出原点。 例如，HTTP URL 'https://example.org/foo/bar' 的原点是 ASCII 字符串 'https://example.org'。 如果给定的字符串无法解析为 URL 或无法导出有效的原点，则将抛出错误。

一个 URL 对象，或任何具有 origin 属性的对象，可以作为 origin 传递，在这种情况下，将使用 origin 属性的值。 origin 属性的值 *必须* 是正确序列化的 ASCII 原点。

或者，当使用 http2.createSecureServer() 方法创建一个新的 HTTP/2 服务器时，可以使用 origins 选项。

import { createSecureServer } from 'node:http2';
const options = getSecureOptionsSomehow();
options.origins = ['https://example.com', 'https://example.org'];
const server = createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});const http2 = require('node:http2');
const options = getSecureOptionsSomehow();
options.origins = ['https://example.com', 'https://example.org'];
const server = http2.createSecureServer(options);
server.on('stream', (stream) => {
  stream.respond();
  stream.end('ok');
});copy

事件：'altsvc'#

• alt <string>
• origin <string>
• streamId <number>

每当客户端收到 ALTSVC 帧时，就会触发 'altsvc' 事件。该事件会传递 ALTSVC 值、源 (origin) 和流 ID。如果 ALTSVC 帧中未提供 origin，则 origin 将为空字符串。

import { connect } from 'node:http2';
const client = connect('https://example.org');

client.on('altsvc', (alt, origin, streamId) => {
  console.log(alt);
  console.log(origin);
  console.log(streamId);
});const http2 = require('node:http2');
const client = http2.connect('https://example.org');

client.on('altsvc', (alt, origin, streamId) => {
  console.log(alt);
  console.log(origin);
  console.log(streamId);
});copy

事件：'origin'#

• origins <string[]>

每当客户端收到 ORIGIN 帧时，就会触发 'origin' 事件。 该事件会传递一个 origin 字符串数组。http2session.originSet 将更新以包含收到的源。

import { connect } from 'node:http2';
const client = connect('https://example.org');

client.on('origin', (origins) => {
  for (let n = 0; n < origins.length; n++)
    console.log(origins[n]);
});const http2 = require('node:http2');
const client = http2.connect('https://example.org');

client.on('origin', (origins) => {
  for (let n = 0; n < origins.length; n++)
    console.log(origins[n]);
});copy

只有在使用安全 TLS 连接时才会触发 'origin' 事件。

clienthttp2session.request(headers[, options])#

• headers <HTTP/2 标头对象> | <Array>

• options <Object>

  • endStream <boolean> 如果最初应该关闭 Http2Stream 的可写端，则为 true，例如在发送不应期望有效负载主体的 GET 请求时。
  • exclusive <boolean> 当 true 并且 parent 标识父流时，创建的流将成为父流的唯一直接依赖项，所有其他现有依赖项都将成为新创建的流的依赖项。默认值：false。
  • parent <number> 指定新创建的流所依赖的流的数字标识符。
  • weight <number> 指定流相对于具有相同 parent 的其他流的相对依赖性。该值是介于 1 和 256 之间的数字（包括 1 和 256）。
  • waitForTrailers <boolean> 当为 true 时，Http2Stream 将在发送完最后一个 DATA 帧后触发 'wantTrailers' 事件。
  • signal <AbortSignal> 可用于中止正在进行的请求的 AbortSignal。

• 返回值：<ClientHttp2Stream>

对于 HTTP/2 客户端 Http2Session 实例，http2session.request() 创建并返回一个 Http2Stream 实例，该实例可用于向连接的服务器发送 HTTP/2 请求。

当第一次创建 ClientHttp2Session 时，套接字可能尚未连接。 如果在此期间调用 clienthttp2session.request()，则实际请求将被推迟到套接字准备就绪。 如果在执行实际请求之前关闭 session，则会抛出 ERR_HTTP2_GOAWAY_SESSION 错误。

仅当 http2session.type 等于 http2.constants.NGHTTP2_SESSION_CLIENT 时，此方法才可用。

import { connect, constants } from 'node:http2';
const clientSession = connect('https://localhost:1234');
const {
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
} = constants;

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' });
req.on('response', (headers) => {
  console.log(headers[HTTP2_HEADER_STATUS]);
  req.on('data', (chunk) => { /* .. */ });
  req.on('end', () => { /* .. */ });
});const http2 = require('node:http2');
const clientSession = http2.connect('https://localhost:1234');
const {
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
} = http2.constants;

const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' });
req.on('response', (headers) => {
  console.log(headers[HTTP2_HEADER_STATUS]);
  req.on('data', (chunk) => { /* .. */ });
  req.on('end', () => { /* .. */ });
});copy

当设置了 options.waitForTrailers 选项时，会在将要发送的最后一个有效负载数据块排队后立即触发 'wantTrailers' 事件。 然后可以调用 http2stream.sendTrailers() 方法以将尾部标头发送到对等方。

当设置了 options.waitForTrailers 时，Http2Stream 不会在传输完最后一个 DATA 帧时自动关闭。 用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 才能关闭 Http2Stream。

当使用 AbortSignal 设置 options.signal，然后调用相应 AbortController 上的 abort 时，请求将触发一个包含 AbortError 错误的 'error' 事件。

如果未在 headers 中指定 :method 和 :path 伪标头，则它们分别默认为

• :method = 'GET'
• :path = /

stream.respond({
  'content-type': 'text/html; charset=utf-8',
  ':status': 200,
}); copy

Http2Stream 生命周期#

事件：'aborted'#

每当 Http2Stream 实例在通信过程中异常中止时，就会触发 'aborted' 事件。 其侦听器不希望有任何参数。

仅当 Http2Stream 可写端尚未结束时，才会触发 'aborted' 事件。

事件：'close'#

销毁 Http2Stream 时，会触发 'close' 事件。 触发此事件后，Http2Stream 实例不再可用。

可以使用 http2stream.rstCode 属性检索关闭流时使用的 HTTP/2 错误代码。 如果代码不是 NGHTTP2_NO_ERROR（0）之外的任何值，则也会触发 'error' 事件。

事件：'error'#

• error <Error>

在处理 Http2Stream 期间发生错误时，会触发 'error' 事件。

事件：'frameError'#

• type <integer> 帧类型。
• code <integer> 错误代码。
• id <integer> 流 ID (如果帧与流无关，则为 0)。

尝试发送帧时发生错误时，会触发 'frameError' 事件。 调用时，处理函数将接收一个整数参数，用于标识帧类型，以及一个整数参数，用于标识错误代码。 触发 'frameError' 事件后，将立即销毁 Http2Stream 实例。

事件：'ready'#

当 Http2Stream 已打开、已分配一个 id 并且可以使用时，将触发 'ready' 事件。 侦听器不希望有任何参数。

事件：'timeout'#

当此 Http2Stream 在使用 http2stream.setTimeout() 设置的毫秒数内未收到任何活动时，会触发 'timeout' 事件。其监听器不期望任何参数。

事件：'trailers'#

• headers <HTTP/2 标头对象> 描述标头的对象
• flags <number> 关联的数字标志

当收到与尾部标头字段关联的标头块时，会触发 'trailers' 事件。监听器回调函数将传递 HTTP/2 标头对象和与标头关联的标志。

如果在收到 trailers 之前调用了 http2stream.end()，并且没有读取或监听传入的数据，则可能不会触发此事件。

stream.on('trailers', (headers, flags) => {
  console.log(headers);
}); copy

事件：'wantTrailers'#

当 Http2Stream 将要发送的最后一个 DATA 帧排入队列，并且 Http2Stream 准备好发送尾部标头时，会触发 'wantTrailers' 事件。当发起请求或响应时，必须设置 waitForTrailers 选项才能触发此事件。

http2stream.aborted#

• <boolean>

如果 Http2Stream 实例异常中止，则设置为 true。设置后，将已触发 'aborted' 事件。

http2stream.bufferSize#

• <number>

此属性显示当前缓冲以待写入的字符数。有关详细信息，请参见 net.Socket.bufferSize。

http2stream.close(code[, callback])#

• code <number> 无符号 32 位整数，用于标识错误代码。默认值: http2.constants.NGHTTP2_NO_ERROR (0x00)。
• callback <Function> 一个可选函数，注册以监听 'close' 事件。

通过向连接的 HTTP/2 对等方发送 RST_STREAM 帧来关闭 Http2Stream 实例。

http2stream.closed#

• <boolean>

如果 Http2Stream 实例已关闭，则设置为 true。

http2stream.destroyed#

• <boolean>

如果 Http2Stream 实例已被销毁且不再可用，则设置为 true。

http2stream.endAfterHeaders#

• <boolean>

如果在收到的请求或响应 HEADERS 帧中设置了 END_STREAM 标志，指示不应接收任何其他数据，并且 Http2Stream 的可读端将关闭，则设置为 true。

http2stream.id#

• <number> | <undefined>

此 Http2Stream 实例的数字流标识符。如果尚未分配流标识符，则设置为 undefined。

http2stream.pending#

• <boolean>

如果尚未为 Http2Stream 实例分配数字流标识符，则设置为 true。

http2stream.priority(options)#

• options <Object>
  • exclusive <boolean> 当 true 且 parent 标识父流时，此流将成为父流的唯一直接依赖项，所有其他现有依赖项将成为此流的依赖项。默认值: false。
  • parent <number> 指定此流所依赖的流的数字标识符。
  • weight <number> 指定流相对于具有相同 parent 的其他流的相对依赖性。该值是介于 1 和 256 之间的数字（包括 1 和 256）。
  • silent <boolean> 当 true 时，在本地更改优先级，而不向连接的对等方发送 PRIORITY 帧。

更新此 Http2Stream 实例的优先级。

http2stream.rstCode#

• <number>

设置为当 Http2Stream 在从连接的对等方收到 RST_STREAM 帧、调用 http2stream.close() 或 http2stream.destroy() 后被销毁时报告的 RST_STREAM 错误代码。如果 Http2Stream 尚未关闭，则将为 undefined。

http2stream.sentHeaders#

• <HTTP/2 标头对象>

一个包含为此 Http2Stream 发送的出站标头的对象。

http2stream.sentInfoHeaders#

• <HTTP/2 标头对象[]>

一个对象数组，包含为此 Http2Stream 发送的出站信息性（附加）标头。

http2stream.sentTrailers#

• <HTTP/2 标头对象>

一个包含为此 HttpStream 发送的出站 trailers 的对象。

http2stream.session#

• <Http2Session>

对拥有此 Http2Stream 的 Http2Session 实例的引用。在 Http2Stream 实例被销毁后，该值将为 undefined。

http2stream.setTimeout(msecs, callback)#

• msecs <number>
• callback <Function>

import { connect, constants } from 'node:http2';
const client = connect('http://example.org:8000');
const { NGHTTP2_CANCEL } = constants;
const req = client.request({ ':path': '/' });

// Cancel the stream if there's no activity after 5 seconds
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL));const http2 = require('node:http2');
const client = http2.connect('http://example.org:8000');
const { NGHTTP2_CANCEL } = http2.constants;
const req = client.request({ ':path': '/' });

// Cancel the stream if there's no activity after 5 seconds
req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL));copy

http2stream.state#

提供有关 Http2Stream 的当前状态的各种信息。

• <Object>
  • localWindowSize <number> 连接的对等方可以在没有收到 WINDOW_UPDATE 的情况下为此 Http2Stream 发送的字节数。
  • state <number> 一个标志，指示由 nghttp2 确定的 Http2Stream 的底层当前状态。
  • localClose <number> 如果此 Http2Stream 已在本地关闭，则为 1。
  • remoteClose <number> 如果此 Http2Stream 已被远程关闭，则为 1。
  • sumDependencyWeight <number> 所有依赖于此 Http2Stream 的 Http2Stream 实例的总权重，如使用 PRIORITY 帧指定的那样。
  • weight <number> 此 Http2Stream 的优先级权重。

此 Http2Stream 的当前状态。

http2stream.sendTrailers(headers)#

• headers <HTTP/2 标头对象>

向连接的 HTTP/2 对等方发送尾部 HEADERS 帧。此方法将导致 Http2Stream 立即关闭，并且只能在触发 'wantTrailers' 事件后调用。当发送请求或发送响应时，必须设置 options.waitForTrailers 选项，以便在最终 DATA 帧之后保持 Http2Stream 打开，以便可以发送 trailers。

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respond(undefined, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' });
  });
  stream.end('Hello World');
});const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond(undefined, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ xyz: 'abc' });
  });
  stream.end('Hello World');
});copy

HTTP/1 规范禁止 trailers 包含 HTTP/2 伪标头字段（例如，':method'、':path' 等）。

事件：'continue'#

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

事件：'headers'#

• headers <HTTP/2 标头对象>
• flags <number>

当为流接收到额外的标头块时，例如当接收到 1xx 信息性标头块时，会触发 'headers' 事件。监听器回调函数将传递 HTTP/2 标头对象和与标头关联的标志。

stream.on('headers', (headers, flags) => {
  console.log(headers);
}); copy

事件：'push'#

• headers <HTTP/2 标头对象>
• flags <number>

当接收到服务器推送流的响应标头时，会触发 'push' 事件。监听器回调函数将传递 HTTP/2 标头对象和与标头关联的标志。

stream.on('push', (headers, flags) => {
  console.log(headers);
}); copy

事件：'response'#

• headers <HTTP/2 标头对象>
• flags <number>

当从连接的 HTTP/2 服务器为此流接收到响应 HEADERS 帧时，会触发 'response' 事件。 使用两个参数调用侦听器：一个包含接收到的 HTTP/2 标头对象的 Object，以及与标头关联的标志。

import { connect } from 'node:http2';
const client = connect('https://localhost');
const req = client.request({ ':path': '/' });
req.on('response', (headers, flags) => {
  console.log(headers[':status']);
});const http2 = require('node:http2');
const client = http2.connect('https://localhost');
const req = client.request({ ':path': '/' });
req.on('response', (headers, flags) => {
  console.log(headers[':status']);
});copy

http2stream.additionalHeaders(headers)#

• headers <HTTP/2 标头对象>

向连接的 HTTP/2 对等方发送附加的信息性 HEADERS 帧。

http2stream.headersSent#

• <boolean>

如果已发送标头，则为 True，否则为 false（只读）。

http2stream.pushAllowed#

• <boolean>

只读属性，映射到远程客户端最近的 SETTINGS 帧的 SETTINGS_ENABLE_PUSH 标志。 如果远程对等方接受推送流，则为 true，否则为 false。 对于同一 Http2Session 中的每个 Http2Stream，设置都是相同的。

http2stream.pushStream(headers[, options], callback)#

• headers <HTTP/2 标头对象>
• options <Object>
  • exclusive <boolean> 当 true 并且 parent 标识父流时，创建的流将成为父流的唯一直接依赖项，所有其他现有依赖项都将成为新创建的流的依赖项。默认值：false。
  • parent <number> 指定新创建的流所依赖的流的数字标识符。
• callback <Function> 推送流启动后调用的回调。
  • err <Error>
  • pushStream <ServerHttp2Stream> 返回的 pushStream 对象。
  • headers <HTTP/2 Headers Object> pushStream 启动时使用的标头对象。

启动推送流。 调用该回调时，会将为推送流创建的新的 Http2Stream 实例作为第二个参数传递，或者将 Error 作为第一个参数传递。

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => {
    if (err) throw err;
    pushStream.respond({ ':status': 200 });
    pushStream.end('some pushed data');
  });
  stream.end('some data');
});const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => {
    if (err) throw err;
    pushStream.respond({ ':status': 200 });
    pushStream.end('some pushed data');
  });
  stream.end('some data');
});copy

不允许在 HEADERS 帧中设置推送流的权重。 将 weight 值传递给 http2stream.priority，并将 silent 选项设置为 true，以启用并发流之间的服务器端带宽平衡。

不允许从推送流中调用 http2stream.pushStream()，否则会引发错误。

http2stream.respond([headers[, options]])#

• headers <HTTP/2 标头对象>
• options <Object>
  • endStream <boolean> 设置为 true 以指示响应将不包含有效负载数据。
  • waitForTrailers <boolean> 当为 true 时，Http2Stream 将在发送完最后一个 DATA 帧后触发 'wantTrailers' 事件。

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.end('some data');
});const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 });
  stream.end('some data');
});copy

启动响应。 当设置了 options.waitForTrailers 选项时，将在排队发送的最后一个有效负载数据块之后立即发出 'wantTrailers' 事件。 然后可以使用 http2stream.sendTrailers() 方法将尾部标头字段发送到对等方。

当设置了 options.waitForTrailers 时，Http2Stream 不会在传输完最后一个 DATA 帧时自动关闭。 用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 才能关闭 Http2Stream。

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 }, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
  stream.end('some data');
});const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respond({ ':status': 200 }, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
  stream.end('some data');
});copy

http2stream.respondWithFD(fd[, headers[, options]])#

• fd <number> | <FileHandle> 可读文件描述符。
• headers <HTTP/2 标头对象>
• options <Object>
  • statCheck <Function>
  • waitForTrailers <boolean> 当为 true 时，Http2Stream 将在发送完最后一个 DATA 帧后触发 'wantTrailers' 事件。
  • offset <number> 开始读取的偏移位置。
  • length <number> 从 fd 发送的数据量。

启动响应，其数据从给定的文件描述符读取。 不会对给定的文件描述符执行任何验证。 如果尝试使用文件描述符读取数据时发生错误，则将使用标准 INTERNAL_ERROR 代码使用 RST_STREAM 帧关闭 Http2Stream。

使用时，Http2Stream 对象的 Duplex 接口将自动关闭。

import { createServer } from 'node:http2';
import { openSync, fstatSync, closeSync } from 'node:fs';

const server = createServer();
server.on('stream', (stream) => {
  const fd = openSync('/some/file', 'r');

  const stat = fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers);
  stream.on('close', () => closeSync(fd));
});const http2 = require('node:http2');
const fs = require('node:fs');

const server = http2.createServer();
server.on('stream', (stream) => {
  const fd = fs.openSync('/some/file', 'r');

  const stat = fs.fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers);
  stream.on('close', () => fs.closeSync(fd));
});copy

可以指定可选的 options.statCheck 函数，以使用户代码有机会根据给定 fd 的 fs.Stat 详细信息设置其他内容标头。 如果提供了 statCheck 函数，则 http2stream.respondWithFD() 方法将执行 fs.fstat() 调用以收集有关提供的文件描述符的详细信息。

可以使用 offset 和 length 选项将响应限制为特定的范围子集。 例如，这可用于支持 HTTP Range 请求。

文件描述符或 FileHandle 在流关闭时不会关闭，因此一旦不再需要，就需要手动关闭它。 不支持同时为多个流并发使用相同的文件描述符，并且可能导致数据丢失。 支持在流完成后重新使用文件描述符。

当设置了 options.waitForTrailers 选项时，将在排队发送的最后一个有效负载数据块之后立即发出 'wantTrailers' 事件。 然后可以使用 http2stream.sendTrailers() 方法将尾部标头字段发送到对等方。

当设置了 options.waitForTrailers 时，Http2Stream 不会在最终 DATA 帧传输时自动关闭。 用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 以关闭 Http2Stream。

import { createServer } from 'node:http2';
import { openSync, fstatSync, closeSync } from 'node:fs';

const server = createServer();
server.on('stream', (stream) => {
  const fd = openSync('/some/file', 'r');

  const stat = fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });

  stream.on('close', () => closeSync(fd));
});const http2 = require('node:http2');
const fs = require('node:fs');

const server = http2.createServer();
server.on('stream', (stream) => {
  const fd = fs.openSync('/some/file', 'r');

  const stat = fs.fstatSync(fd);
  const headers = {
    'content-length': stat.size,
    'last-modified': stat.mtime.toUTCString(),
    'content-type': 'text/plain; charset=utf-8',
  };
  stream.respondWithFD(fd, headers, { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });

  stream.on('close', () => fs.closeSync(fd));
});copy

http2stream.respondWithFile(path[, headers[, options]])#

• path <string> | <Buffer> | <URL>
• headers <HTTP/2 标头对象>
• options <Object>
  • statCheck <Function>
  • onError <Function> 在发送之前发生错误时调用的回调函数。
  • waitForTrailers <boolean> 当为 true 时，Http2Stream 将在发送完最后一个 DATA 帧后触发 'wantTrailers' 事件。
  • offset <number> 开始读取的偏移位置。
  • length <number> 从 fd 发送的数据量。

发送一个常规文件作为响应。 path 必须指定一个常规文件，否则将在 Http2Stream 对象上发出 'error' 事件。

使用时，Http2Stream 对象的 Duplex 接口将自动关闭。

可以指定可选的 options.statCheck 函数，以使用户代码有机会根据给定文件的 fs.Stat 详细信息设置其他内容标头

如果在尝试读取文件数据时发生错误，则将使用标准 INTERNAL_ERROR 代码使用 RST_STREAM 帧关闭 Http2Stream。 如果定义了 onError 回调，则将调用它。 否则，将销毁流。

使用文件路径的示例

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString();
  }

  function onError(err) {
    // stream.respond() can throw if the stream has been destroyed by
    // the other side.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // Perform actual error handling.
      console.error(err);
    }
    stream.end();
  }

  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck, onError });
});const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    headers['last-modified'] = stat.mtime.toUTCString();
  }

  function onError(err) {
    // stream.respond() can throw if the stream has been destroyed by
    // the other side.
    try {
      if (err.code === 'ENOENT') {
        stream.respond({ ':status': 404 });
      } else {
        stream.respond({ ':status': 500 });
      }
    } catch (err) {
      // Perform actual error handling.
      console.error(err);
    }
    stream.end();
  }

  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck, onError });
});copy

options.statCheck 函数也可用于通过返回 false 来取消发送操作。 例如，有条件请求可以检查 stat 结果，以确定文件是否已修改，以返回适当的 304 响应

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    // Check the stat here...
    stream.respond({ ':status': 304 });
    return false; // Cancel the send operation
  }
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck });
});const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  function statCheck(stat, headers) {
    // Check the stat here...
    stream.respond({ ':status': 304 });
    return false; // Cancel the send operation
  }
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { statCheck });
});copy

将自动设置 content-length 标头字段。

可以使用 offset 和 length 选项将响应限制为特定的范围子集。 例如，这可用于支持 HTTP Range 请求。

options.onError 函数也可用于处理在启动文件传递之前可能发生的所有错误。 默认行为是销毁流。

当设置了 options.waitForTrailers 选项时，将在排队发送的最后一个有效负载数据块之后立即发出 'wantTrailers' 事件。 然后可以使用 http2stream.sendTrailers() 方法将尾部标头字段发送到对等方。

当设置了 options.waitForTrailers 时，Http2Stream 不会在传输完最后一个 DATA 帧时自动关闭。 用户代码必须调用 http2stream.sendTrailers() 或 http2stream.close() 才能关闭 Http2Stream。

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream) => {
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
});const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream) => {
  stream.respondWithFile('/some/file',
                         { 'content-type': 'text/plain; charset=utf-8' },
                         { waitForTrailers: true });
  stream.on('wantTrailers', () => {
    stream.sendTrailers({ ABC: 'some value to send' });
  });
});copy

事件: 'checkContinue'#

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

如果注册了 'request' 监听器或 http2.createServer() 提供了回调函数，则每次收到带有 HTTP Expect: 100-continue 的请求时都会发出 'checkContinue' 事件。 如果没有监听此事件，服务器将自动响应状态 100 Continue（如果适用）。

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

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

事件: 'connection'#

• socket <stream.Duplex>

当建立新的 TCP 流时，会发出此事件。 socket 通常是 net.Socket 类型的对象。 通常，用户不想访问此事件。

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

事件: 'request'#

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

每次有请求时都会发出。 每个会话可能有多个请求。 请参阅 兼容性 API。

事件: 'session'#

• session <ServerHttp2Session>

当 Http2Server 创建新的 Http2Session 时，会发出 'session' 事件。

事件: 'sessionError'#

• error <Error>
• session <ServerHttp2Session>

当与 Http2Server 关联的 Http2Session 对象发出 'error' 事件时，会发出 'sessionError' 事件。

事件: 'stream'#

• stream <Http2Stream> 对流的引用
• headers <HTTP/2 标头对象> 描述标头的对象
• flags <number> 关联的数字标志
• rawHeaders <Array> 包含原始标头名称及其相应值的数组。

当与服务器关联的 Http2Session 发出 'stream' 事件时，会发出 'stream' 事件。

另请参阅 Http2Session 的 'stream' 事件。

import { createServer, constants } from 'node:http2';
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = constants;

const server = createServer();
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});const http2 = require('node:http2');
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = http2.constants;

const server = http2.createServer();
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});copy

事件: 'timeout'#

当服务器在通过 http2server.setTimeout() 设置的给定毫秒数内没有活动时，会发出 'timeout' 事件。 默认值: 0（无超时）

server.close([callback])#

• callback <Function>

阻止服务器建立新的会话。这不会阻止由于 HTTP/2 会话的持久性而创建新的请求流。要优雅地关闭服务器，请对所有活动会话调用 http2session.close()。

如果提供了 callback，则只有在所有活动会话都已关闭后才会调用它，即使服务器已经停止允许建立新会话。 有关更多详细信息，请参见 net.Server.close()。

server[Symbol.asyncDispose]()#

调用 server.close() 并返回一个在服务器关闭时兑现的 Promise。

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

• msecs <number> 默认值: 0（无超时）
• callback <Function>
• 返回: <Http2Server>

用于设置 http2 服务器请求的超时值，并设置一个回调函数，该函数在 Http2Server 上在 msecs 毫秒后没有活动时被调用。

给定的回调函数注册为 'timeout' 事件的监听器。

如果 callback 不是函数，将抛出一个新的 ERR_INVALID_ARG_TYPE 错误。

server.timeout#

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

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

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

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

server.updateSettings([settings])#

• settings <HTTP/2 Settings Object>

用于使用提供的设置更新服务器。

对于无效的 settings 值，抛出 ERR_HTTP2_INVALID_SETTING_VALUE。

对于无效的 settings 参数，抛出 ERR_INVALID_ARG_TYPE。

事件: 'checkContinue'#

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

如果注册了 'request' 监听器，或者 http2.createSecureServer() 提供了回调函数，则每次收到带有 HTTP Expect: 100-continue 的请求时，都会发出 'checkContinue' 事件。 如果没有监听此事件，服务器将自动响应状态 100 Continue（如果合适）。

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

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

事件: 'connection'#

• socket <stream.Duplex>

当建立新的 TCP 流时，在 TLS 握手开始之前，会发出此事件。 socket 通常是 net.Socket 类型的对象。 通常用户不希望访问此事件。

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

事件: 'request'#

• request <http2.Http2ServerRequest>
• response <http2.Http2ServerResponse>

每次有请求时都会发出。 每个会话可能有多个请求。 请参阅 兼容性 API。

事件: 'session'#

• session <ServerHttp2Session>

当 Http2SecureServer 创建新的 Http2Session 时，会发出 'session' 事件。

事件: 'sessionError'#

• error <Error>
• session <ServerHttp2Session>

当与 Http2SecureServer 关联的 Http2Session 对象发出 'error' 事件时，会发出 'sessionError' 事件。

事件: 'stream'#

• stream <Http2Stream> 对流的引用
• headers <HTTP/2 标头对象> 描述标头的对象
• flags <number> 关联的数字标志
• rawHeaders <Array> 包含原始标头名称及其相应值的数组。

当与服务器关联的 Http2Session 发出 'stream' 事件时，会发出 'stream' 事件。

另请参阅 Http2Session 的 'stream' 事件。

import { createSecureServer, constants } from 'node:http2';
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = constants;

const options = getOptionsSomehow();

const server = createSecureServer(options);
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});const http2 = require('node:http2');
const {
  HTTP2_HEADER_METHOD,
  HTTP2_HEADER_PATH,
  HTTP2_HEADER_STATUS,
  HTTP2_HEADER_CONTENT_TYPE,
} = http2.constants;

const options = getOptionsSomehow();

const server = http2.createSecureServer(options);
server.on('stream', (stream, headers, flags) => {
  const method = headers[HTTP2_HEADER_METHOD];
  const path = headers[HTTP2_HEADER_PATH];
  // ...
  stream.respond({
    [HTTP2_HEADER_STATUS]: 200,
    [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain; charset=utf-8',
  });
  stream.write('hello ');
  stream.end('world');
});copy

事件: 'timeout'#

当使用 http2secureServer.setTimeout() 设置的时间后，服务器上没有任何活动时，会发出 'timeout' 事件。 默认值: 2 分钟。

事件: 'unknownProtocol'#

• socket <stream.Duplex>

当连接的客户端无法协商允许的协议（即 HTTP/2 或 HTTP/1.1）时，会发出 'unknownProtocol' 事件。 事件处理程序接收用于处理的套接字。 如果没有为此事件注册监听器，则连接将被终止。 可以使用传递给 http2.createSecureServer() 的 'unknownProtocolTimeout' 选项指定超时。

在早期版本的 Node.js 中，如果 allowHTTP1 为 false 且在 TLS 握手期间，客户端要么不发送 ALPN 扩展，要么发送不包含 HTTP/2 (h2) 的 ALPN 扩展，则会发出此事件。 较新版本的 Node.js 仅当 allowHTTP1 为 false 且客户端不发送 ALPN 扩展时才发出此事件。 如果客户端发送不包含 HTTP/2（或者如果 allowHTTP1 为 true，则不包含 HTTP/1.1）的 ALPN 扩展，则 TLS 握手将失败，并且不会建立安全连接。

请参阅兼容性 API。

server.close([callback])#

• callback <Function>

阻止服务器建立新的会话。这不会阻止由于 HTTP/2 会话的持久性而创建新的请求流。要优雅地关闭服务器，请对所有活动会话调用 http2session.close()。

如果提供了 callback，则只有在所有活动会话都已关闭后才会调用它，即使服务器已经停止允许建立新会话。 有关更多详细信息，请参见 tls.Server.close()。

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

• msecs <number> 默认值: 120000（2 分钟）
• callback <Function>
• 返回: <Http2SecureServer>

用于设置 http2 安全服务器请求的超时值，并设置一个回调函数，该函数在 Http2SecureServer 上在 msecs 毫秒后没有活动时被调用。

给定的回调函数注册为 'timeout' 事件的监听器。

如果 callback 不是函数，将抛出一个新的 ERR_INVALID_ARG_TYPE 错误。

server.timeout#

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

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

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

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

server.updateSettings([settings])#

• settings <HTTP/2 Settings Object>

用于使用提供的设置更新服务器。

对于无效的 settings 值，抛出 ERR_HTTP2_INVALID_SETTING_VALUE。

对于无效的 settings 参数，抛出 ERR_INVALID_ARG_TYPE。

RST_STREAM 和 GOAWAY 的错误代码#

值	名称	常量
0x00	无错误	http2.constants.NGHTTP2_NO_ERROR
0x01	协议错误	http2.constants.NGHTTP2_PROTOCOL_ERROR
0x02	内部错误	http2.constants.NGHTTP2_INTERNAL_ERROR
0x03	流量控制错误	http2.constants.NGHTTP2_FLOW_CONTROL_ERROR
0x04	设置超时	http2.constants.NGHTTP2_SETTINGS_TIMEOUT
0x05	流已关闭	http2.constants.NGHTTP2_STREAM_CLOSED
0x06	帧大小错误	http2.constants.NGHTTP2_FRAME_SIZE_ERROR
0x07	拒绝流	http2.constants.NGHTTP2_REFUSED_STREAM
0x08	取消	http2.constants.NGHTTP2_CANCEL
0x09	压缩错误	http2.constants.NGHTTP2_COMPRESSION_ERROR
0x0a	连接错误	http2.constants.NGHTTP2_CONNECT_ERROR
0x0b	冷静一下	http2.constants.NGHTTP2_ENHANCE_YOUR_CALM
0x0c	安全性不足	http2.constants.NGHTTP2_INADEQUATE_SECURITY
0x0d	需要 HTTP/1.1	http2.constants.NGHTTP2_HTTP_1_1_REQUIRED

当使用 http2server.setTimeout() 设置的给定毫秒数内在服务器上没有活动时，会发出 'timeout' 事件。

const headers = {
  ':status': '200',
  'content-type': 'text-plain',
  'ABC': ['has', 'more', 'than', 'one', 'value'],
};

stream.respond(headers); copy

import { createServer } from 'node:http2';
const server = createServer();
server.on('stream', (stream, headers) => {
  console.log(headers[':path']);
  console.log(headers.ABC);
});const http2 = require('node:http2');
const server = http2.createServer();
server.on('stream', (stream, headers) => {
  console.log(headers[':path']);
  console.log(headers.ABC);
});copy

敏感请求头#

HTTP2 请求头可以标记为敏感，这意味着 HTTP/2 请求头压缩算法永远不会索引它们。对于熵值较低且可能被攻击者认为有价值的请求头值（例如 Cookie 或 Authorization），这样做是有意义的。要实现这一点，请将请求头名称作为数组添加到 [http2.sensitiveHeaders] 属性中。

const headers = {
  ':status': '200',
  'content-type': 'text-plain',
  'cookie': 'some-cookie',
  'other-sensitive-header': 'very secret data',
  [http2.sensitiveHeaders]: ['cookie', 'other-sensitive-header'],
};

stream.respond(headers); copy

对于某些请求头（例如 Authorization 和较短的 Cookie 请求头），此标志会自动设置。

此属性也为接收到的请求头设置。它将包含所有标记为敏感的请求头的名称，包括自动标记的那些。

事件: 'aborted'#

当 Http2ServerRequest 实例在通信过程中异常中止时，会触发 'aborted' 事件。

只有在 Http2ServerRequest 的可写端未结束时，才会触发 'aborted' 事件。

事件: 'close'#

表示底层的 Http2Stream 已关闭。与 'end' 类似，此事件每个响应仅发生一次。

request.aborted#

• <boolean>

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

request.authority#

• <string>

请求授权伪标头字段。 由于 HTTP/2 允许请求设置 :authority 或 host，因此该值来自 req.headers[':authority']（如果存在）。 否则，它来自 req.headers['host']。

request.complete#

• <boolean>

如果请求已完成、中止或销毁，则 request.complete 属性将为 true。

request.connection#

• <net.Socket> | <tls.TLSSocket>

请参阅 request.socket。

request.destroy([error])#

• error <Error>

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

如果流已销毁，则它不执行任何操作。

request.headers#

• <Object>

请求/响应标头对象。

标头名称和值的键值对。 标头名称采用小写形式。

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

请参阅 HTTP/2 标头对象。

在 HTTP/2 中，请求路径、主机名、协议和方法表示为以 : 字符为前缀的特殊标头（例如，':path'）。 这些特殊标头将包含在 request.headers 对象中。 必须小心不要无意中修改这些特殊标头，否则可能会发生错误。 例如，从请求中删除所有标头会导致发生错误

removeAllHeaders(request.headers);
assert(request.url);   // Fails because the :path header has been removed copy

request.httpVersion#

• <string>

对于服务器请求，是客户端发送的 HTTP 版本。 对于客户端响应，是连接到的服务器的 HTTP 版本。 返回 '2.0'。

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

request.method#

• <string>

请求方法，是一个字符串。 只读。 示例: 'GET', 'DELETE'。

request.rawHeaders#

• <string[]>

完全按照接收方式的原始请求/响应标头列表。

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

标头名称不区分大小写，并且不会合并重复项。

// 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

request.rawTrailers#

• <string[]>

完全按照接收方式的原始请求/响应预告片键和值。 仅在 'end' 事件中填充。

request.scheme#

• <string>

请求 scheme 伪标头字段，指示目标 URL 的 scheme 部分。

request.setTimeout(msecs, callback)#

• msecs <number>
• callback <Function>
• 返回: <http2.Http2ServerRequest>

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

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

request.socket#

• <net.Socket> | <tls.TLSSocket>

返回一个 Proxy 对象，该对象充当 net.Socket（或 tls.TLSSocket），但根据 HTTP/2 逻辑应用 getter、setter 和方法。

destroyed、readable 和 writable 属性将从 request.stream 中检索并在其上设置。

destroy、emit、end、on 和 once 方法将在 request.stream 上调用。

setTimeout 方法将在 request.stream.session 上调用。

pause、read、resume 和 write 将引发代码为 ERR_HTTP2_NO_SOCKET_MANIPULATION 的错误。 有关更多信息，请参阅 Http2Session 和套接字。

所有其他交互将直接路由到套接字。 通过 TLS 支持，使用 request.socket.getPeerCertificate() 获取客户端的身份验证详细信息。

request.stream#

• <Http2Stream>

支持请求的 Http2Stream 对象。

request.trailers#

• <Object>

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

request.url#

• <string>

请求 URL 字符串。 这仅包含实际 HTTP 请求中存在的 URL。 如果请求是

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

然后 request.url 将是

'/status?name=ryan' copy

要将 url 解析为其各个部分，可以使用 new URL()

$ node
> new URL('/status?name=ryan', 'http://example.com')
URL {
  href: 'http://example.com/status?name=ryan',
  origin: 'http://example.com',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'example.com',
  hostname: 'example.com',
  port: '',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
} copy

事件: 'close'#

表示在调用 response.end() 或能够刷新之前，底层的 Http2Stream 已终止。

事件: 'finish'#

在发送响应时触发。 更具体地说，当响应标头和主体的最后一段已移交给 HTTP/2 多路复用以通过网络传输时，会触发此事件。 它并不意味着客户端已收到任何内容。

在此事件之后，响应对象上不会再触发任何事件。

response.addTrailers(headers)#

• headers <Object>

此方法将 HTTP 尾部标头（标头，但在消息末尾）添加到响应。

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

response.appendHeader(name, value)#

• name <string>
• value <string> | <string[]>

将单个标头值追加到标头对象。

如果该值为数组，则等效于多次调用此方法。

如果该标头之前没有值，则等效于调用 response.setHeader()。

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

// Returns headers including "set-cookie: a" and "set-cookie: b"
const server = http2.createServer((req, res) => {
  res.setHeader('set-cookie', 'a');
  res.appendHeader('set-cookie', 'b');
  res.writeHead(200);
  res.end('ok');
}); copy

response.connection#

• <net.Socket> | <tls.TLSSocket>

请参阅 response.socket。

response.createPushResponse(headers, callback)#

• headers <HTTP/2 标头对象> 描述标头的对象
• callback <Function> 一旦 http2stream.pushStream() 完成后调用，或者当创建推送的 Http2Stream 的尝试失败或被拒绝时，或者在调用 http2stream.pushStream() 方法之前 Http2ServerRequest 的状态关闭时
  • err <Error>
  • res <http2.Http2ServerResponse> 新创建的 Http2ServerResponse 对象

使用给定的标头调用 http2stream.pushStream()，并将给定的 Http2Stream 包装在新创建的 Http2ServerResponse 上作为回调参数（如果成功）。 当 Http2ServerRequest 关闭时，将调用回调并显示错误 ERR_HTTP2_INVALID_STREAM。

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

• data <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• 返回: <this>

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

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

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

response.finished#

• <boolean>

布尔值，指示响应是否已完成。 初始值为 false。 在 response.end() 执行后，该值将为 true。

response.getHeader(name)#

• name <string>
• 返回: <string>

读取已排队但尚未发送到客户端的标头。 名称不区分大小写。

const contentType = response.getHeader('content-type'); copy

response.getHeaderNames()#

• 返回: <string[]>

返回一个数组，其中包含当前传出标头的唯一名称。 所有标头名称都是小写的。

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

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

response.getHeaders()#

• 返回: <Object>

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

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

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

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

response.hasHeader(name)#

• name <string>
• 返回: <boolean>

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

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

response.headersSent#

• <boolean>

如果已发送标头，则为 True，否则为 false（只读）。

response.removeHeader(name)#

• name <string>

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

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

response.req#

• <http2.Http2ServerRequest>

对原始 HTTP2 request 对象的引用。

response.sendDate#

• <boolean>

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

仅应禁用此项以进行测试； HTTP 要求响应中包含 Date 标头。

response.setHeader(name, value)#

• name <string>
• value <string> | <string[]>

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

response.setHeader('Content-Type', 'text/html; charset=utf-8'); copy

或

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

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

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

// Returns content-type = text/plain
const server = http2.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html; charset=utf-8');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('ok');
}); copy

response.setTimeout(msecs[, callback])#

• msecs <number>
• callback <Function>
• 返回: <http2.Http2ServerResponse>

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

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

response.socket#

• <net.Socket> | <tls.TLSSocket>

返回一个 Proxy 对象，该对象充当 net.Socket（或 tls.TLSSocket），但根据 HTTP/2 逻辑应用 getter、setter 和方法。

destroyed、readable 和 writable 属性将从 response.stream 中检索并在其上设置。

将在 response.stream 上调用 destroy、emit、end、on 和 once 方法。

将在 response.stream.session 上调用 setTimeout 方法。

pause、read、resume 和 write 将引发代码为 ERR_HTTP2_NO_SOCKET_MANIPULATION 的错误。 有关更多信息，请参阅 Http2Session 和套接字。

所有其他交互将直接路由到套接字。

import { createServer } from 'node:http2';
const server = createServer((req, res) => {
  const ip = req.socket.remoteAddress;
  const port = req.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);const http2 = require('node:http2');
const server = http2.createServer((req, res) => {
  const ip = req.socket.remoteAddress;
  const port = req.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);copy

response.statusCode#

• <number>

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

response.statusCode = 404; copy

在将响应标头发送到客户端后，此属性指示发送出的状态代码。

response.statusMessage#

• <string>

HTTP/2 不支持状态消息 (RFC 7540 8.1.2.4)。 它返回一个空字符串。

response.stream#

• <Http2Stream>

支持响应的 Http2Stream 对象。

response.writableEnded#

• <boolean>

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

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

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <Function>
• 返回: <boolean>

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

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

在 node:http 模块中，当请求是 HEAD 请求时，响应主体会被省略。 类似地，204 和 304 响应不得包含消息主体。

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

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

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

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

response.writeContinue()#

向客户端发送状态 100 Continue，表明应发送请求正文。 请参阅 Http2Server 和 Http2SecureServer 上的 'checkContinue' 事件。

response.writeEarlyHints(hints)#

• hints <Object>

向客户端发送状态 103 Early Hints，其中包含 Link 标头，表明用户代理可以预加载/预连接链接的资源。 hints 是一个对象，其中包含要与早期提示消息一起发送的标头的值。

例子

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

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

• statusCode <number>
• statusMessage <string>
• headers <Object> | <Array>
• 返回: <http2.Http2ServerResponse>

向请求发送响应标头。 状态代码是一个 3 位数的 HTTP 状态代码，如 404。 最后一个参数 headers 是响应标头。

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

为了与 HTTP/1 兼容，可以传递一个人类可读的 statusMessage 作为第二个参数。 然而，由于 statusMessage 在 HTTP/2 中没有任何意义，因此该参数将不起作用，并且会发出一个进程警告。

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

Content-Length 以字节为单位，而不是字符。 可以使用 Buffer.byteLength() API 来确定给定编码中的字节数。 在出站消息中，Node.js 不会检查 Content-Length 和正在传输的主体的长度是否相等。 但是，在接收消息时，当 Content-Length 与实际有效负载大小不匹配时，Node.js 将自动拒绝消息。

在调用 response.end() 之前，此方法在一个消息上最多只能调用一次。

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

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

// Returns content-type = text/plain
const server = http2.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html; charset=utf-8');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('ok');
}); copy

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