Node.js v21.7.2 文件

判斷是否不支援加密#

Node.js 可以建置，而不包含對 node:crypto 模組的支援。在這種情況下，嘗試從 node:http2 import 或呼叫 require('node:http2') 會導致引發錯誤。

使用 CommonJS 時，可以透過 try/catch 捕捉拋出的錯誤

let http2;
try {
  http2 = require('node:http2');
} catch (err) {
  console.error('http2 support is disabled!');
} copy

使用詞彙 ESM import 關鍵字時，只有在嘗試載入模組之前（例如，使用預載模組）註冊 process.on('uncaughtException') 處理常式，才能捕捉錯誤

使用 ESM 時，如果程式碼有可能在未啟用加密支援的 Node.js 版本上執行，請考慮使用 import() 函式，而非詞彙 import 關鍵字

let http2;
try {
  http2 = await import('node:http2');
} catch (err) {
  console.error('http2 support is disabled!');
} copy

核心 API#

核心 API 提供低階介面，專門設計用於支援 HTTP/2 協定功能。特別是不設計用於與現有的 HTTP/1 模組 API 相容。不過，相容性 API 是相容的。

http2 核心 API 在用戶端和伺服器之間的對稱性遠高於 http API。例如，大多數事件，例如 'error'、'connect' 和 'stream'，都可以由用戶端程式碼或伺服器端程式碼發出。

伺服器端範例#

以下說明使用核心 API 的簡單 HTTP/2 伺服器。由於沒有已知的瀏覽器支援 未加密的 HTTP/2，因此在與瀏覽器用戶端通訊時，必須使用 http2.createSecureServer()。

const http2 = require('node:http2');
const fs = require('node:fs');

const server = http2.createSecureServer({
  key: fs.readFileSync('localhost-privkey.pem'),
  cert: fs.readFileSync('localhost-cert.pem'),
});
server.on('error', (err) => console.error(err));

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

server.listen(8443); copy

要產生此範例的憑證和金鑰，請執行

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout localhost-privkey.pem -out localhost-cert.pem copy

用戶端範例#

以下說明 HTTP/2 用戶端

const http2 = require('node:http2');
const fs = require('node:fs');
const client = http2.connect('https://127.0.0.1:8443', {
  ca: fs.readFileSync('localhost-cert.pem'),
});
client.on('error', (err) => console.error(err));

const req = client.request({ ':path': '/' });

req.on('response', (headers, flags) => {
  for (const name in headers) {
    console.log(`${name}: ${headers[name]}`);
  }
});

req.setEncoding('utf8');
let data = '';
req.on('data', (chunk) => { data += chunk; });
req.on('end', () => {
  console.log(`\n${data}`);
  client.close();
});
req.end(); copy

類別：Http2Session#

• 延伸：<EventEmitter>

http2.Http2Session 類別的執行個體表示 HTTP/2 用戶端與伺服器之間的活動通訊會話。此類別的執行個體並非供使用者程式碼直接建構。

每個 Http2Session 執行個體會表現出略微不同的行為，視其是以伺服器或用戶端身分運作而定。http2session.type 屬性可用於判斷 Http2Session 運作的模式。在伺服器端，使用者程式碼很少需要直接使用 Http2Session 物件，大多數動作通常透過與 Http2Server 或 Http2Stream 物件互動來執行。

使用者程式碼不會直接建立 Http2Session 執行個體。伺服器端的 Http2Session 執行個體是由 Http2Server 執行個體在收到新的 HTTP/2 連線時建立。用戶端端的 Http2Session 執行個體是使用 http2.connect() 方法建立。

Http2Session 與 socket#

每個 Http2Session 執行個體在建立時會與一個 net.Socket 或 tls.TLSSocket 進行關聯。當 Socket 或 Http2Session 其中之一被銷毀時，兩者都會被銷毀。

由於 HTTP/2 協定施加了特定的序列化和處理需求，不建議使用者程式碼從與 Http2Session 繫結的 Socket 執行個體讀取資料或寫入資料。這麼做可能會讓 HTTP/2 會話進入不確定的狀態，導致會話和 socket 無法使用。

一旦 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 <數字> GOAWAY 框架中指定的 HTTP/2 錯誤代碼。
• lastStreamID <數字> 遠端對等方成功處理的最後一個串流的 ID（如果未指定 ID，則為 0）。
• opaqueData <Buffer> 如果 GOAWAY 框架中包含其他不透明資料，將傳遞包含該資料的 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 <數字> 相關的數字旗標
• rawHeaders <陣列> 包含原始標頭名稱及其各自值的陣列。

當建立新的 Http2Stream 時，會發出 'stream' 事件。

const http2 = require('node:http2');
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

在伺服器端，使用者程式碼通常不會直接偵聽此事件，而是會為 http2.createServer() 和 http2.createSecureServer() 分別傳回的 net.Server 或 tls.Server 執行個體發出的 'stream' 事件註冊處理常式，如下面的範例所示

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#

• <字串> | <未定義>

如果 Http2Session 尚未連線至 socket，則值為 undefined；如果 Http2Session 未連線至 TLSSocket，則為 h2c；否則會傳回已連線 TLSSocket 本身的 alpnProtocol 屬性值。

http2session.close([callback])#

• callback <函式>

優雅地關閉 Http2Session，允許任何現有的串流自行完成，並防止建立新的 Http2Stream 實例。關閉後，如果沒有開啟的 Http2Stream 實例，可能會 呼叫 http2session.destroy()。

如果指定，callback 函式會註冊為 'close' 事件的處理常式。

http2session.closed#

• <布林值>

如果此 Http2Session 實例已關閉，則為 true，否則為 false。

http2session.connecting#

• <布林值>

如果此 Http2Session 實例仍在連線中，則為 true；在發出 connect 事件和/或呼叫 http2.connect 回呼之前，會設為 false。

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

• error <錯誤> 如果 Http2Session 因錯誤而被銷毀，則為 錯誤 物件。
• code <數字> 要在最後的 GOAWAY 框架中傳送的 HTTP/2 錯誤碼。如果未指定，且 error 未定義，則預設為 INTERNAL_ERROR，否則預設為 NO_ERROR。

立即終止 Http2Session 和關聯的 net.Socket 或 tls.TLSSocket。

毀損後，Http2Session 會發出 'close' 事件。如果 error 不是未定義，則會在 'close' 事件之前立即發出 'error' 事件。

如果與 Http2Session 關聯的任何剩餘開啟 Http2Streams，這些也會被毀損。

http2session.destroyed#

• <布林值>

如果此 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> 包含要傳送在 GOAWAY 框架中的其他資料的 TypedArray 或 DataView 執行個體。

傳送 GOAWAY 框架給已連線的對等方，不關閉 Http2Session。

http2session.localSettings#

• <HTTP/2 設定物件>

描述此 Http2Session 的目前區域設定的無原型物件。區域設定是特定於 此 Http2Session 執行個體的。

http2session.originSet#

• <string[]> | <undefined>

如果 Http2Session 已連線到 TLSSocket，originSet 屬性會傳回 Http2Session 可能被視為具有權限的來源 Array。

僅在使用安全的 TLS 連線時，originSet 屬性才可用。

http2session.pendingSettingsAck#

• <布林值>

表示 Http2Session 目前是否正在等待已傳送 SETTINGS 框架的確認。呼叫 http2session.settings() 方法後，將會為 true。一旦所有已傳送的 SETTINGS 框架都已確認，將會為 false。

http2session.ping([payload, ]callback)#

• payload <Buffer> | <TypedArray> | <DataView> 選擇性 ping 酬載。
• callback <函式>
• 傳回：<boolean>

傳送 PING 框架給已連線的 HTTP/2 對等方。必須提供 callback 函式。如果已傳送 PING，方法會傳回 true，否則傳回 false。

未完成 (未確認) ping 的最大數量由 maxOutstandingPings 組態選項決定。預設最大值為 10。

若有提供，payload 必須是包含 8 位元組資料的 Buffer、TypedArray 或 DataView，這些資料會隨 PING 傳輸，並隨 ping 確認一起傳回。

呼叫回函會以三個引數呼叫：一個錯誤引數，如果 PING 已成功確認，則為 null；一個 duration 引數，報告從 ping 送出到收到確認之間經過的毫秒數；以及一個包含 8 位元組 PING payload 的 Buffer。

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 是要設定的總視窗大小，而不是增量。

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 <函式>

用於設定一個回呼函式，當在 Http2Session 上沒有活動超過 msecs 毫秒時會呼叫此函式。所提供的 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 上呼叫。

所有其他互動都會直接路由到 socket。

http2session.state#

提供有關 Http2Session 目前狀態的雜項資訊。

• <Object>
  • effectiveLocalWindowSize <number> Http2Session 的目前本機 (接收) 流量控制視窗大小。
  • effectiveRecvDataLength <number> 自上次流量控制 WINDOW_UPDATE 以來已接收的目前位元組數。
  • nextStreamID <number> 這個 Http2Session 下次建立新的 Http2Stream 時要使用的數字識別碼。
  • localWindowSize <數字> 遠端對等端可以在不收到 WINDOW_UPDATE 的情況下傳送的位元組數。
  • lastProcStreamID <數字> 最近收到 HEADERS 或 DATA 框架的 Http2Stream 的數字識別碼。
  • remoteWindowSize <數字> 這個 Http2Session 可以在不收到 WINDOW_UPDATE 的情況下傳送的位元組數。
  • outboundQueueSize <數字> 目前在這個 Http2Session 的傳出佇列中的框架數。
  • deflateDynamicTableSize <數字> 傳出標頭壓縮狀態表的目前大小（以位元組為單位）。
  • inflateDynamicTableSize <數字> 傳入標頭壓縮狀態表的目前大小（以位元組為單位）。

描述此 Http2Session 目前狀態的物件。

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

• settings <HTTP/2 設定物件>
• callback <函式> 一旦連線建立，或如果連線已經建立，則立即呼叫的回呼。
  • err <錯誤> | <null>
  • settings <HTTP/2 設定物件> 已更新的 settings 物件。
  • duration <整數>

更新此 Http2Session 的目前本機設定，並傳送新的 SETTINGS 框架給已連線的 HTTP/2 對等方。

呼叫後，http2session.pendingSettingsAck 屬性會在會話等待遠端對等方確認新的設定時為 true。

新的設定不會在收到 SETTINGS 確認，且 'localSettings' 事件發出前生效。在確認仍未收到時，可以傳送多個 SETTINGS 框架。

http2session.type#

• <數字>

如果此 Http2Session 執行個體是伺服器，則 http2session.type 會等於 http2.constants.NGHTTP2_SESSION_SERVER；如果執行個體是客戶端，則會等於 http2.constants.NGHTTP2_SESSION_CLIENT。

http2session.unref()#

在這個 Http2Session 執行個體的底層 net.Socket 上呼叫 unref()。

類別：ServerHttp2Session#

• 延伸：<Http2Session>

serverhttp2session.altsvc(alt, originOrStream)#

• alt <字串> 替代服務組態的說明，如 RFC 7838 所定義。
• originOrStream <數字> | <字串> | <URL> | <物件> 指定來源的 URL 字串 (或具有 origin 屬性的 物件)，或由 http2stream.id 屬性提供的活動 Http2Stream 的數字識別碼。

提交一個 ALTSVC 框架（如 RFC 7838 所定義）至已連線的用戶端。

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 通訊協定在主機 'example.org' 上的 TCP/IP 埠 81 上可用。主機和埠必須包含在引號 (") 字元內。

可以指定多個備用，例如：'h2="example.org:81", h2=":82"'。

協定識別碼（範例中的「'h2'」）可以是任何有效的 ALPN 協定識別碼。

這些值的語法並未由 Node.js 實作驗證，且會照使用者提供的內容傳遞，或從對等方接收。

serverhttp2session.origin(...origins)#

• origins <字串> | <URL> | <物件> 一個或多個 URL 字串，作為個別參數傳遞。

提交 ORIGIN 框架（由 RFC 8336 定義）給已連線的客戶端，以宣傳伺服器有能力提供具公信力回應的來源組。

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 選項

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

類別：ClientHttp2Session#

• 延伸：<Http2Session>

事件：'altsvc'#

• alt <字串>
• origin <字串>
• streamId <數字>

當客戶端收到 ALTSVC 框架時，就會發出 'altsvc' 事件。此事件會與 ALTSVC 值、來源和串流 ID 一起發出。如果 ALTSVC 框架中未提供 origin，則 origin 會是空字串。

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 <字串陣列>

當客戶端收到 ORIGIN 框架時，就會發出 'origin' 事件。此事件會與 origin 字串陣列一起發出。http2session.originSet 會更新為包含已接收的來源。

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 標頭物件>

• options <物件>

  • endStream <布林值> 如果 Http2Stream 可寫入 端應在最初關閉，例如在傳送不應期待有效負載本文的 GET 要求時，則為 true。
  • exclusive <布林值> 當 true 且 parent 識別父串流時，建立的串流會成為父項的唯一直接相依項，所有其他現有相依項會成為新建立串流的相依項。預設：false。
  • parent <數字> 指定新建立串流所相依的串流的數字識別碼。
  • weight <數字> 指定串流相對於具有相同 parent 的其他串流的相對相依性。值為介於 1 到 256（包含）之間的數字。
  • waitForTrailers <布林值> 當 true 時，Http2Stream 會在最後一個 DATA 框架已傳送後發出 'wantTrailers' 事件。
  • signal <中斷訊號> 可用於中斷進行中要求的中斷訊號。

• 傳回：<ClientHttp2Stream>

僅適用於 HTTP/2 Client Http2Session 實例，http2session.request() 會建立並傳回 Http2Stream 實例，可用於將 HTTP/2 要求傳送至已連線的伺服器。

當 ClientHttp2Session 首次建立時，socket 可能尚未連線。如果在此期間呼叫 clienthttp2session.request()，實際要求會延後，直到 socket 準備就緒。如果 session 在實際要求執行前已關閉，會擲回 ERR_HTTP2_GOAWAY_SESSION。

此方法僅在 http2session.type 等於 http2.constants.NGHTTP2_SESSION_CLIENT 時才可用。

const http2 = require('node:http2');
const clientSession = http2.connect('https://127.0.0.1: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 時，傳輸最後一個 DATA 框架時，Http2Stream 仍不會自動關閉。使用者程式碼必須呼叫 http2stream.sendTrailers() 或 http2stream.close() 來關閉 Http2Stream。

使用 AbortSignal 設定 options.signal，然後呼叫對應的 AbortController 上的 abort，要求會發出一個包含 AbortError 錯誤的 'error' 事件。

:method 和 :path 偽標頭未在 headers 中指定，它們分別預設為

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

類別：Http2Stream#

• 延伸：<stream.Duplex>

Http2Stream 類別的每個執行個體代表 Http2Session 執行個體上的雙向 HTTP/2 通訊串流。任何單一 Http2Session 在其生命週期內最多可以有 2³¹-1 個 Http2Stream 執行個體。

使用者程式碼不會直接建構 Http2Stream 實例。相反地，這些實例會透過 Http2Session 實例建立、管理並提供給使用者程式碼。在伺服器上，Http2Stream 實例會在回應傳入 HTTP 要求（並透過 'stream' 事件傳遞給使用者程式碼）時，或在回應呼叫 http2stream.pushStream() 方法時建立。在用戶端上，Http2Stream 實例會在呼叫 http2session.request() 方法時，或在回應傳入 'push' 事件時建立並傳回。

Http2Stream 類別是 ServerHttp2Stream 和 ClientHttp2Stream 類別的基礎，每個類別分別由伺服器或用戶端側專門使用。

所有 Http2Stream 實例都是 Duplex 串流。Duplex 的 Writable 端用於將資料傳送至已連線的對等端，而 Readable 端用於接收已連線的對等端傳送的資料。

Http2Stream 的預設文字字元編碼為 UTF-8。當使用 Http2Stream 傳送文字時，請使用 'content-type' 標頭設定字元編碼。

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

Http2Stream 生命週期#

建立#

在伺服器端，ServerHttp2Stream 的實例會在下列情況建立：

• 收到具有先前未使用串流 ID 的新的 HTTP/2 HEADERS 框架；
• 呼叫 http2stream.pushStream() 方法。

在用戶端端，ClientHttp2Stream 的實例會在呼叫 http2session.request() 方法時建立。

在用戶端上，如果父 Http2Session 尚未完全建立，則 http2session.request() 傳回的 Http2Stream 實例可能無法立即使用。在這種情況下，對 Http2Stream 呼叫的操作會緩衝，直到發出 'ready' 事件。使用者程式碼很少需要直接處理 'ready' 事件。可以透過檢查 http2stream.id 的值來判斷 Http2Stream 的準備狀態。如果值為 undefined，則串流尚未準備好使用。

銷毀#

所有 Http2Stream 執行個體會在下列情況下銷毀：

• 已連線對等方收到串流的 RST_STREAM 框架，且（僅限於用戶端串流）已讀取待處理資料。
• 已呼叫 http2stream.close() 方法，且（僅限於用戶端串流）已讀取待處理資料。
• 已呼叫 http2stream.destroy() 或 http2session.destroy() 方法。

銷毀 Http2Stream 執行個體時，系統會嘗試傳送 RST_STREAM 框架給已連線對等方。

銷毀 Http2Stream 執行個體時，將會發出 'close' 事件。由於 Http2Stream 是 stream.Duplex 的執行個體，如果串流資料目前正在傳送，也會發出 'end' 事件。如果 http2stream.destroy() 呼叫時傳遞 Error 作為第一個引數，也可能會發出 'error' 事件。

銷毀 Http2Stream 之後，http2stream.destroyed 屬性會變成 true，而 http2stream.rstCode 屬性會指定 RST_STREAM 錯誤碼。銷毀後，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'` 事件。呼叫時，處理常式會收到一個整數引數，用於識別框架類型，以及一個整數引數，用於識別錯誤碼。`Http2Stream` 執行個體會在發出 `'frameError'` 事件後立即銷毀。

事件：'ready'#

當 `Http2Stream` 已開啟、已指定 `id` 且可用時，將發出 `'ready'` 事件。監聽器不預期有任何引數。

事件：'timeout'#

在未收到此 `Http2Stream` 的任何活動，且時間超過使用 `http2stream.setTimeout()` 設定的毫秒數後，將發出 `'timeout'` 事件。其監聽器不預期有任何引數。

事件：'trailers'#

• headers <HTTP/2 標頭物件> 描述標頭的物件
• flags <數字> 相關的數字旗標

當收到與尾端標頭欄位相關聯的標頭區塊時，會發出 'trailers' 事件。會將 HTTP/2 標頭物件 和與標頭相關聯的旗標傳遞給監聽器回呼。

如果在收到尾端標頭之前呼叫 http2stream.end() 且未讀取或監聽輸入資料，則可能不會發出此事件。

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

事件：'wantTrailers'#

當 Http2Stream 已將最後的 DATA 框架排隊準備在框架上傳送，且 Http2Stream 已準備好傳送尾端標頭時，會發出 'wantTrailers' 事件。在啟動要求或回應時，必須設定 waitForTrailers 選項才能發出此事件。

http2stream.aborted#

• <布林值>

如果 Http2Stream 實例異常中止，則設為 true。設定後，會發出 'aborted' 事件。

http2stream.bufferSize#

• <數字>

此屬性顯示目前緩衝以寫入的字元數。有關詳細資訊，請參閱 net.Socket.bufferSize。

http2stream.close(code[, callback])#

• code <number> 識別錯誤代碼的未簽署 32 位元整數。預設：http2.constants.NGHTTP2_NO_ERROR (0x00)。
• callback <函數> 註冊以偵聽 'close' 事件的選用函數。

透過將 RST_STREAM 框架傳送給已連線的 HTTP/2 對等方來關閉 Http2Stream 執行個體。

http2stream.closed#

• <布林值>

如果 Http2Stream 執行個體已關閉，則設為 true。

http2stream.destroyed#

• <布林值>

如果 Http2Stream 執行個體已毀損且不再可用，則設為 true。

http2stream.endAfterHeaders#

• <布林值>

如果在收到的請求或回應標頭框架中設定了 END_STREAM 旗標，則設為 true，表示不應再接收其他資料，且 Http2Stream 的可讀取端將會關閉。

http2stream.id#

• <數字> | <未定義>

此 Http2Stream 執行個體的數字串流識別碼。如果尚未指派串流識別碼，則設為 undefined。

http2stream.pending#

• <布林值>

如果 Http2Stream 執行個體尚未指派數字串流識別碼，則設為 true。

http2stream.priority(options)#

• options <物件>
  • exclusive <布林值> 當 true 且 parent 識別父串流時，此串流會成為父串流的唯一直接依賴項，所有其他現有依賴項都會成為此串流的依賴項。預設：false。
  • parent <數字> 指定此串流所依賴的串流的數字識別碼。
  • weight <數字> 指定串流相對於具有相同 parent 的其他串流的相對相依性。值為介於 1 到 256（包含）之間的數字。
  • silent <布林值> 當 true 時，會在本地變更優先順序，而不會傳送 PRIORITY 框架給已連線的對等方。

更新此 Http2Stream 實例的優先順序。

http2stream.rstCode#

• <數字>

設定為 RST_STREAM 錯誤碼，當 Http2Stream 在從已連線的對等方收到 RST_STREAM 框架、呼叫 http2stream.close() 或 http2stream.destroy() 之後被銷毀時報告。如果 Http2Stream 尚未關閉，則會是 undefined。

http2stream.sentHeaders#

• <HTTP/2 標頭物件>

包含為此 Http2Stream 傳送的傳出標頭的物件。

http2stream.sentInfoHeaders#

• <HTTP/2 標頭物件[]>

包含為此 Http2Stream 傳送的傳出資訊性（其他）標頭的物件陣列。

http2stream.sentTrailers#

• <HTTP/2 標頭物件>

包含傳送給此 HttpStream 的傳出預告片的物件。

http2stream.session#

• <Http2Session>

擁有此 Http2Stream 的 Http2Session 實例的參考。在 Http2Stream 實例被銷毀後，此值將會是 undefined。

http2stream.setTimeout(msecs, callback)#

• msecs <number>
• callback <函式>

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 標頭物件>

傳送尾端 HEADERS 框架給已連線的 HTTP/2 對等方。此方法將導致 Http2Stream 立即關閉，且只能在發出 'wantTrailers' 事件後呼叫。傳送要求或傳送回應時，必須設定 options.waitForTrailers 選項，才能在最後一個 DATA 框架後保持 Http2Stream 開啟，以便可以傳送尾端。

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 規範禁止拖曳層包含 HTTP/2 偽標頭欄位（例如 ':method'、':path' 等）。

類別：ClientHttp2Stream#

• 延伸 <Http2Stream>

ClientHttp2Stream 類別是 Http2Stream 的延伸，專門用於 HTTP/2 Client。Client 上的 Http2Stream 執行個體提供事件，例如僅與 Client 相關的 'response' 和 'push'。

事件：'continue'#

當伺服器傳送 100 Continue 狀態時發出，通常是因為要求包含 Expect: 100-continue。這是指示 Client 應傳送要求主體的指令。

事件：'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>

當收到 Server Push 串流的回應標頭時，會發出 '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，以及與標頭相關聯的旗標。

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

類別：ServerHttp2Stream#

• 延伸：<Http2Stream>

ServerHttp2Stream 類別是 Http2Stream 的延伸，專門用於 HTTP/2 伺服器。伺服器上的 Http2Stream 實例提供其他方法，例如 http2stream.pushStream() 和 http2stream.respond()，這些方法只與伺服器相關。

http2stream.additionalHeaders(headers)#

• headers <HTTP/2 標頭物件>

傳送其他資訊性 HEADERS 框架給連線的 HTTP/2 對等方。

http2stream.headersSent#

• <布林值>

如果已傳送標頭，則為 True，否則為 false（唯讀）。

http2stream.pushAllowed#

• <布林值>

唯讀屬性，對應於遠端用戶端最近的 SETTINGS 框架的 SETTINGS_ENABLE_PUSH 旗標。如果遠端對等端接受推送串流，則為 true，否則為 false。設定在同一個 Http2Session 中的每個 Http2Stream 中都是相同的。

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

• headers <HTTP/2 標頭物件>
• options <物件>
  • exclusive <布林值> 當 true 且 parent 識別父串流時，建立的串流會成為父項的唯一直接相依項，所有其他現有相依項會成為新建立串流的相依項。預設：false。
  • parent <數字> 指定新建立串流所相依的串流的數字識別碼。
• callback <Function> 推送串流啟動後呼叫的回呼。
  • err <Error>
  • pushStream <ServerHttp2Stream> 傳回的 pushStream 物件。
  • headers <HTTP/2 Headers Object> pushStream 啟動時使用的標頭物件。

啟動推送串流。回呼會呼叫新的 Http2Stream 實例，該實例是為推送串流建立的，並傳遞為第二個參數，或傳遞 Error 為第一個參數。

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 <物件>
  • endStream <boolean> 設定為 true 以指出回應不會包含酬載資料。
  • waitForTrailers <布林值> 當 true 時，Http2Stream 會在最後一個 DATA 框架已傳送後發出 'wantTrailers' 事件。

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 時，傳輸最後一個 DATA 框架時，Http2Stream 仍不會自動關閉。使用者程式碼必須呼叫 http2stream.sendTrailers() 或 http2stream.close() 來關閉 Http2Stream。

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 <數字> | <FileHandle> 可讀取檔案描述符。
• headers <HTTP/2 標頭物件>
• options <物件>
  • statCheck <函式>
  • waitForTrailers <布林值> 當 true 時，Http2Stream 會在最後一個 DATA 框架已傳送後發出 'wantTrailers' 事件。
  • offset <數字> 開始讀取的偏移位置。
  • length <數字> 從 fd 傳送的資料量。

啟動回應，其資料從指定的檔案描述符讀取。不會對指定的檔案描述符執行驗證。如果在嘗試使用檔案描述符讀取資料時發生錯誤，Http2Stream 將使用標準 INTERNAL_ERROR 碼，使用 RST_STREAM 框架關閉。

使用時，Http2Stream 物件的 Duplex 介面將自動關閉。

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 範圍要求。

當串流關閉時，檔案描述符或 FileHandle 不會關閉，因此在不再需要時需要手動關閉。不支援同時將同一個檔案描述符用於多個串流，這可能會導致資料遺失。支援在串流結束後重新使用檔案描述符。

當設定 options.waitForTrailers 選項時，在排入最後一塊要傳送的負載資料後，將立即發出 'wantTrailers' 事件。然後可以使用 http2stream.sendTrailers() 方法將尾隨標頭欄位傳送給對等方。

當設定 options.waitForTrailers 時，Http2Stream 絕不會在傳輸最後一個 DATA 框架時自動關閉。使用者程式碼必須呼叫 http2stream.sendTrailers() 或 http2stream.close() 來關閉 Http2Stream。

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 <字串> | <Buffer> | <URL>
• headers <HTTP/2 標頭物件>
• options <物件>
  • statCheck <函式>
  • onError <函式> 在傳送前發生錯誤時呼叫的回呼函式。
  • waitForTrailers <布林值> 當 true 時，Http2Stream 會在最後一個 DATA 框架已傳送後發出 'wantTrailers' 事件。
  • offset <數字> 開始讀取的偏移位置。
  • length <數字> 從 fd 傳送的資料量。

將常規檔案作為回應傳送。path 必須指定常規檔案，否則會在 Http2Stream 物件上發出 'error' 事件。

使用時，Http2Stream 物件的 Duplex 介面將自動關閉。

可以指定選用的 options.statCheck 函式，讓使用者程式碼有機會根據指定檔案的 fs.Stat 詳細資料設定其他內容標頭。

如果在嘗試讀取檔案資料時發生錯誤，Http2Stream 會使用標準 INTERNAL_ERROR 碼，透過 RST_STREAM 框架關閉。如果已定義 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 回應。

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 範圍要求。

options.onError 函式也可以用來處理在開始傳送檔案之前可能發生的所有錯誤。預設行為是銷毀串流。

當設定 options.waitForTrailers 選項時，在排入最後一塊要傳送的負載資料後，將立即發出 'wantTrailers' 事件。然後可以使用 http2stream.sendTrailers() 方法將尾隨標頭欄位傳送給對等方。

設定 options.waitForTrailers 時，傳輸最後一個 DATA 框架時，Http2Stream 仍不會自動關閉。使用者程式碼必須呼叫 http2stream.sendTrailers() 或 http2stream.close() 來關閉 Http2Stream。

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

類別：Http2Server#

• 延伸：<net.Server>

使用 http2.createServer() 函式建立 Http2Server 的執行個體。Http2Server 類別並未由 node:http2 模組直接匯出。

事件：'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 <數字> 相關的數字旗標
• rawHeaders <陣列> 包含原始標頭名稱及其各自值的陣列。

當與伺服器關聯的 Http2Session 發出 'stream' 事件時，會發出 'stream' 事件。

另請參閱 Http2Session 的 'stream' 事件。

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 <函式>

停止伺服器建立新的工作階段。由於 HTTP/2 工作階段的持續特性，這並不會阻止建立新的要求串流。若要正常關閉伺服器，請對所有活動工作階段呼叫 http2session.close()。

如果提供了 callback，則在所有活動工作階段關閉之前不會呼叫它，即使伺服器已停止允許新的工作階段。請參閱 net.Server.close() 以取得更多詳細資訊。

server[Symbol.asyncDispose]()#

呼叫 server.close()，並在伺服器關閉時傳回一個承諾。

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

• msecs <number> 預設值：0（無逾時）
• callback <函式>
• 傳回：<Http2Server>

用於設定 http2 伺服器要求的逾時值，並設定一個在 Http2Server 上沒有活動超過 msecs 毫秒時呼叫的回呼函式。

已註冊提供的回呼作為 'timeout' 事件的監聽器。

如果 callback 不是函式，則會擲回新的 ERR_INVALID_ARG_TYPE 錯誤。

server.timeout#

• <數字> 以毫秒為單位的逾時時間。預設值：0（無逾時）

在假設 Socket 已逾時的毫秒數。

0 的值會停用進入連線的逾時行為。

Socket 逾時邏輯會在連線時設定，因此變更此值只會影響伺服器的新連線，不會影響任何現有連線。

server.updateSettings([settings])#

• settings <HTTP/2 設定物件>

用於以提供的設定更新伺服器。

對於無效的 settings 值，會擲回 ERR_HTTP2_INVALID_SETTING_VALUE。

對於無效的 settings 參數，會擲回 ERR_INVALID_ARG_TYPE。

類別：Http2SecureServer#

• 延伸：<tls.Server>

Http2SecureServer 的執行個體是使用 http2.createSecureServer() 函式建立的。Http2SecureServer 類別並未由 node:http2 模組直接匯出。

事件：'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>

在 TLS 交握開始前，當建立新的 TCP 串流時，會發出此事件。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 <數字> 相關的數字旗標
• rawHeaders <陣列> 包含原始標頭名稱及其各自值的陣列。

當與伺服器關聯的 Http2Session 發出 'stream' 事件時，會發出 'stream' 事件。

另請參閱 Http2Session 的 'stream' 事件。

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' 事件。事件處理常式會收到用於處理的 socket。如果沒有為此事件註冊監聽器，連線會終止。可以使用傳遞給 http2.createSecureServer() 的 'unknownProtocolTimeout' 選項來指定逾時時間。

在早期版本的 Node.js 中，如果 allowHTTP1 為 false，且在 TLS 交握期間，用戶端未傳送 ALPN 擴充功能，或傳送的 ALPN 擴充功能不包含 HTTP/2 (h2)，則會發出此事件。較新版本的 Node.js 僅在 allowHTTP1 為 false 且用戶端未傳送 ALPN 擴充功能時，才會發出此事件。如果用戶端傳送的 ALPN 擴充功能不包含 HTTP/2 (或在 allowHTTP1 為 true 時不包含 HTTP/1.1)，則 TLS 交握將會失敗，且不會建立安全連線。

請參閱 相容性 API。

server.close([callback])#

• callback <函式>

停止伺服器建立新的工作階段。由於 HTTP/2 工作階段的持續特性，這並不會阻止建立新的要求串流。若要正常關閉伺服器，請對所有活動工作階段呼叫 http2session.close()。

如果提供了 callback，則在所有活動的會話關閉之前，不會呼叫它，儘管伺服器已停止允許新的會話。有關更多詳細資訊，請參閱 tls.Server.close()。

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

• msecs <number> 預設值： 120000 (2 分鐘)
• callback <函式>
• 傳回：<Http2SecureServer>

用於設定 http2 安全伺服器要求的逾時值，並設定一個在 Http2SecureServer 上沒有活動超過 msecs 毫秒時呼叫的 callback 函式。

已註冊提供的回呼作為 'timeout' 事件的監聽器。

如果 callback 不是函式，則會擲回新的 ERR_INVALID_ARG_TYPE 錯誤。

server.timeout#

• <數字> 以毫秒為單位的逾時時間。預設值：0（無逾時）

在假設 Socket 已逾時的毫秒數。

0 的值會停用進入連線的逾時行為。

Socket 逾時邏輯會在連線時設定，因此變更此值只會影響伺服器的新連線，不會影響任何現有連線。

server.updateSettings([settings])#

• settings <HTTP/2 設定物件>

用於以提供的設定更新伺服器。

對於無效的 settings 值，會擲回 ERR_HTTP2_INVALID_SETTING_VALUE。

對於無效的 settings 參數，會擲回 ERR_INVALID_ARG_TYPE。

http2.createServer([options][, onRequestHandler])#

• options <物件>
  • maxDeflateDynamicTableSize <數字> 設定用於壓縮標頭欄位的最大動態表格大小。預設：4Kib。
  • maxSettings <數字> 設定每個 SETTINGS 框架的最大設定項目數。允許的最小值為 1。預設：32。
  • maxSessionMemory<數字> 設定 Http2Session 允許使用的最大記憶體。值以百萬位元組為單位表示，例如 1 等於 1 百萬位元組。允許的最小值為 1。這是一個基於信用額度的限制，現有的 Http2Stream 可能導致超過此限制，但當超過此限制時，新的 Http2Stream 執行個體將會被拒絕。目前的 Http2Stream 會話數量、標頭壓縮表格目前的記憶體使用量、目前排隊準備傳送的資料，以及未確認的 PING 和 SETTINGS 框架都計入目前的限制。預設值：10。
  • maxHeaderListPairs <數字> 設定標頭條目的最大數量。這類似於 node:http 模組中的 server.maxHeadersCount 或 request.maxHeadersCount。最小值為 4。預設值：128。
  • maxOutstandingPings <數字> 設定未確認的未完成 ping 的最大數量。預設值：10。
  • maxSendHeaderBlockLength <數字> 設定序列化、壓縮的標頭區塊允許的最大大小。嘗試傳送超過此限制的標頭將導致發出 'frameError' 事件，並關閉和銷毀串流。雖然這設定了整個標頭區塊允許的最大大小，但 nghttp2（內部 http2 函式庫）對每個解壓縮的鍵/值配對都有 65536 的限制。
  • paddingStrategy <數字> 用於決定要對 HEADERS 和 DATA 框架使用多少填充的策略。預設值：http2.constants.PADDING_STRATEGY_NONE。值可以是
    • http2.constants.PADDING_STRATEGY_NONE：不套用填充。
    • http2.constants.PADDING_STRATEGY_MAX：套用由內部實作決定的最大填充量。
    • http2.constants.PADDING_STRATEGY_ALIGNED：嘗試套用足夠的填充，以確保總的框架長度（包括 9 位元組標頭）是 8 的倍數。對於每個框架，都有由目前流量控制狀態和設定決定的最大允許填充位元組數。如果此最大值小於確保對齊所需的計算值，則使用最大值，且總的框架長度不一定在 8 位元組對齊。
  • peerMaxConcurrentStreams <數字> 設定遠端對等方最大並行串流數，就像已收到 SETTINGS 框架一樣。如果遠端對等方設定自己的 maxConcurrentStreams 值，將會被覆寫。預設：100。
  • maxSessionInvalidFrames <整數> 設定在關閉工作階段前容忍的無效框架最大數。預設：1000。
  • maxSessionRejectedStreams <整數> 設定在關閉工作階段前容忍的建立時遭拒絕串流最大數。每個拒絕都與 NGHTTP2_ENHANCE_YOUR_CALM 錯誤相關，應告知對等方不要再開啟任何串流，因此持續開啟串流會被視為行為不當的對等方。預設：100。
  • settings <HTTP/2 設定物件> 在連線時傳送給遠端對等方的初始設定。
  • remoteCustomSettings <陣列> 整數值的陣列決定設定類型，這些類型包含在接收到的 remoteSettings 的 CustomSettings 屬性中。請參閱 Http2Settings 物件的 CustomSettings 屬性，以取得有關允許設定類型的更多資訊。
  • Http1IncomingMessage <http.IncomingMessage> 指定用於 HTTP/1 回退的 IncomingMessage 類別。對於擴充原始 http.IncomingMessage 很實用。預設：http.IncomingMessage。
  • Http1ServerResponse <http.ServerResponse> 指定用於 HTTP/1 回退的 ServerResponse 類別。對於擴充原始 http.ServerResponse 很實用。預設：http.ServerResponse。
  • Http2ServerRequest <http2.Http2ServerRequest> 指定要使用的 Http2ServerRequest 類別。對於擴充原始 Http2ServerRequest 很實用。預設：Http2ServerRequest。
  • Http2ServerResponse <http2.Http2ServerResponse> 指定要使用的 Http2ServerResponse 類別。對於擴充原始 Http2ServerResponse 很實用。預設：Http2ServerResponse。
  • unknownProtocolTimeout <數字> 指定伺服器在發出 'unknownProtocol' 時應等待的逾時時間（毫秒）。如果在該時間內 Socket 尚未被銷毀，伺服器將會銷毀它。預設：10000。
  • ...: 可以提供任何 net.createServer() 選項。
• onRequestHandler <函式> 請參閱 相容性 API
• 傳回：<Http2Server>

傳回一個 net.Server 執行個體，用於建立和管理 Http2Session 執行個體。

由於沒有已知的瀏覽器支援未加密的 HTTP/2，與瀏覽器用戶端進行通訊時，必須使用 http2.createSecureServer()。

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

// Create an unencrypted HTTP/2 server.
// Since there are no browsers known that support
// unencrypted HTTP/2, the use of `http2.createSecureServer()`
// is necessary when communicating with browser clients.
const server = http2.createServer();

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

server.listen(8000); copy

http2.createSecureServer(options[, onRequestHandler])#

• options <物件>
  • allowHTTP1 <boolean> 當設定為 true 時，不支援 HTTP/2 的來信用戶端連線將降級為 HTTP/1.x。請參閱 'unknownProtocol' 事件。請參閱 ALPN 協商。預設值： false。
  • maxDeflateDynamicTableSize <數字> 設定用於壓縮標頭欄位的最大動態表格大小。預設：4Kib。
  • maxSettings <數字> 設定每個 SETTINGS 框架的最大設定項目數。允許的最小值為 1。預設：32。
  • maxSessionMemory<數字> 設定 Http2Session 允許使用的最大記憶體。值以百萬位元組為單位表示，例如 1 等於 1 百萬位元組。允許的最小值為 1。這是一個基於信用額度的限制，現有的 Http2Stream 可能導致超過此限制，但當超過此限制時，新的 Http2Stream 執行個體將會被拒絕。目前的 Http2Stream 會話數量、標頭壓縮表格目前的記憶體使用量、目前排隊準備傳送的資料，以及未確認的 PING 和 SETTINGS 框架都計入目前的限制。預設值：10。
  • maxHeaderListPairs <數字> 設定標頭條目的最大數量。這類似於 node:http 模組中的 server.maxHeadersCount 或 request.maxHeadersCount。最小值為 4。預設值：128。
  • maxOutstandingPings <數字> 設定未確認的未完成 ping 的最大數量。預設值：10。
  • maxSendHeaderBlockLength <number> 設定序列化、壓縮的標頭區塊允許的最大大小。嘗試傳送超過此限制的標頭會導致發出 'frameError' 事件，並關閉及銷毀串流。
  • paddingStrategy <number> 用於決定用於 HEADERS 和 DATA 框架的填充量策略。預設值： http2.constants.PADDING_STRATEGY_NONE。值可以是
    • http2.constants.PADDING_STRATEGY_NONE：不套用填充。
    • http2.constants.PADDING_STRATEGY_MAX：套用由內部實作決定的最大填充量。
    • http2.constants.PADDING_STRATEGY_ALIGNED：嘗試套用足夠的填充，以確保總的框架長度（包括 9 位元組標頭）是 8 的倍數。對於每個框架，都有由目前流量控制狀態和設定決定的最大允許填充位元組數。如果此最大值小於確保對齊所需的計算值，則使用最大值，且總的框架長度不一定在 8 位元組對齊。
  • peerMaxConcurrentStreams <數字> 設定遠端對等方最大並行串流數，就像已收到 SETTINGS 框架一樣。如果遠端對等方設定自己的 maxConcurrentStreams 值，將會被覆寫。預設：100。
  • maxSessionInvalidFrames <整數> 設定在關閉工作階段前容忍的無效框架最大數。預設：1000。
  • maxSessionRejectedStreams <整數> 設定在關閉工作階段前容忍的建立時遭拒絕串流最大數。每個拒絕都與 NGHTTP2_ENHANCE_YOUR_CALM 錯誤相關，應告知對等方不要再開啟任何串流，因此持續開啟串流會被視為行為不當的對等方。預設：100。
  • settings <HTTP/2 設定物件> 在連線時傳送給遠端對等方的初始設定。
  • remoteCustomSettings <Array> 整數值陣列決定設定類型，這些類型包含在接收到的 remoteSettings 的 customSettings 屬性中。請參閱 Http2Settings 物件的 customSettings 屬性，以取得有關允許設定類型的更多資訊。
  • ...: 可以提供任何 tls.createServer() 選項。對於伺服器，通常需要身分選項 (pfx 或 key/cert)。
  • origins <string[]> 起源字串陣列，用於在建立新的伺服器 Http2Session 後立即在 ORIGIN 框架中傳送。
  • unknownProtocolTimeout <number> 指定伺服器在發出 'unknownProtocol' 事件時應等待的逾時時間 (毫秒)。如果在該時間內尚未銷毀 socket，伺服器將銷毀它。預設值： 10000。
• onRequestHandler <函式> 請參閱 相容性 API
• 傳回：<Http2SecureServer>

傳回建立並管理 Http2Session 實例的 tls.Server 實例。

const http2 = require('node:http2');
const fs = require('node:fs');

const options = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
};

// Create a secure HTTP/2 server
const server = http2.createSecureServer(options);

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

server.listen(8443); copy

http2.connect(authority[, options][, listener])#

• authority <字串> | <URL> 要連線的遠端 HTTP/2 伺服器。這必須採用最小的有效 URL 格式，包含 http:// 或 https:// 前置詞、主機名稱和 IP 埠（如果使用非預設埠）。URL 中的使用者資訊（使用者 ID 和密碼）、路徑、查詢字串和片段詳細資料將會被忽略。
• options <物件>
  • maxDeflateDynamicTableSize <數字> 設定用於壓縮標頭欄位的最大動態表格大小。預設：4Kib。
  • maxSettings <數字> 設定每個 SETTINGS 框架的最大設定項目數。允許的最小值為 1。預設：32。
  • maxSessionMemory<數字> 設定 Http2Session 允許使用的最大記憶體。值以百萬位元組為單位表示，例如 1 等於 1 百萬位元組。允許的最小值為 1。這是一個基於信用額度的限制，現有的 Http2Stream 可能導致超過此限制，但當超過此限制時，新的 Http2Stream 執行個體將會被拒絕。目前的 Http2Stream 會話數量、標頭壓縮表格目前的記憶體使用量、目前排隊準備傳送的資料，以及未確認的 PING 和 SETTINGS 框架都計入目前的限制。預設值：10。
  • maxHeaderListPairs <數字> 設定標頭條目的最大數量。這類似於 node:http 模組中的 server.maxHeadersCount 或 request.maxHeadersCount。最小值為 1。預設值：128。
  • maxOutstandingPings <數字> 設定未確認的未完成 ping 的最大數量。預設值：10。
  • maxReservedRemoteStreams <數字> 設定客戶端在任何特定時間接受的保留推播串流最大數量。當目前保留的推播串流數量超過此限制時，伺服器傳送的新推播串流將會自動遭到拒絕。允許的最小值為 0。允許的最大值為 2³²-1。負值會將此選項設定為允許的最大值。預設值：200。
  • maxSendHeaderBlockLength <number> 設定序列化、壓縮的標頭區塊允許的最大大小。嘗試傳送超過此限制的標頭會導致發出 'frameError' 事件，並關閉及銷毀串流。
  • paddingStrategy <number> 用於決定用於 HEADERS 和 DATA 框架的填充量策略。預設值： http2.constants.PADDING_STRATEGY_NONE。值可以是
    • http2.constants.PADDING_STRATEGY_NONE：不套用填充。
    • http2.constants.PADDING_STRATEGY_MAX：套用由內部實作決定的最大填充量。
    • http2.constants.PADDING_STRATEGY_ALIGNED：嘗試套用足夠的填充，以確保總的框架長度（包括 9 位元組標頭）是 8 的倍數。對於每個框架，都有由目前流量控制狀態和設定決定的最大允許填充位元組數。如果此最大值小於確保對齊所需的計算值，則使用最大值，且總的框架長度不一定在 8 位元組對齊。
  • peerMaxConcurrentStreams <數字> 設定遠端對等方最大並行串流數，就像已收到 SETTINGS 框架一樣。如果遠端對等方設定自己的 maxConcurrentStreams 值，將會被覆寫。預設：100。
  • protocol <字串> 要連線的通訊協定，如果未在 authority 中設定。值可能是 'http:' 或 'https:'。預設值：'https:'
  • settings <HTTP/2 設定物件> 在連線時傳送給遠端對等方的初始設定。
  • remoteCustomSettings <陣列> 整數值的陣列決定設定類型，這些類型包含在接收到的 remoteSettings 的 CustomSettings 屬性中。請參閱 Http2Settings 物件的 CustomSettings 屬性，以取得有關允許設定類型的更多資訊。
  • createConnection <函數> 一個可選的回呼，它接收傳遞給 connect 的 URL 實例和 options 物件，並傳回任何 Duplex 串流，用作此階段的連線。
  • ...: 可以提供任何 net.connect() 或 tls.connect() 選項。
  • unknownProtocolTimeout <number> 指定伺服器在發出 'unknownProtocol' 事件時應等待的逾時時間 (毫秒)。如果在該時間內尚未銷毀 socket，伺服器將銷毀它。預設值： 10000。
• listener <函數> 將會註冊為 'connect' 事件的一次性聆聽者。
• 傳回：<ClientHttp2Session>

傳回一個 ClientHttp2Session 實例。

const http2 = require('node:http2');
const client = http2.connect('https://127.0.0.1:1234');

/* Use the client */

client.close(); copy

http2.constants#

RST_STREAM 和 GOAWAY 的錯誤碼#

當伺服器在使用 http2server.setTimeout() 設定的特定毫秒數內沒有任何活動時，會發出 'timeout' 事件。

http2.getDefaultSettings()#

• 傳回：<HTTP/2 設定物件>

傳回一個包含 Http2Session 實例的預設設定的物件。這個方法每次呼叫都會傳回一個新的物件實例，因此傳回的實例可以安全地修改以供使用。

http2.getPackedSettings([settings])#

• settings <HTTP/2 設定物件>
• 傳回：<Buffer>

傳回一個 Buffer 實例，其中包含根據 HTTP/2 規範中指定的 HTTP/2 設定的序列化表示。這適用於 HTTP2-Settings 標頭欄位。

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

const packed = http2.getPackedSettings({ enablePush: false });

console.log(packed.toString('base64'));
// Prints: AAIAAAAA copy

http2.getUnpackedSettings(buf)#

• buf <Buffer> | <TypedArray> 封裝的設定。
• 傳回：<HTTP/2 設定物件>

傳回一個 HTTP/2 設定物件，其中包含由 http2.getPackedSettings() 產生的指定 Buffer 的非序列化設定。

http2.performServerHandshake(socket[, options])#

• socket <stream.Duplex>
• options <物件>
  • ...: 可以提供任何 http2.createServer() 選項。
• 傳回：<ServerHttp2Session>

從現有的 socket 建立 HTTP/2 伺服器工作階段。

http2.sensitiveHeaders#

• <symbol>

此符號可設定為 HTTP/2 標頭物件的屬性，並具有陣列值，以提供視為敏感的標頭清單。詳情請參閱 敏感標頭。

標頭物件#

標頭以 JavaScript 物件的自有屬性表示。屬性金鑰會序列化為小寫。屬性值應該是字串（如果不是，會強制轉換為字串）或字串的Array（為了傳送多個值給每個標頭欄位）。

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

stream.respond(headers); copy

傳遞給回呼函式的標頭物件會有 null 原型。這表示一般的 JavaScript 物件方法，例如 Object.prototype.toString() 和 Object.prototype.hasOwnProperty()，將無法運作。

對於輸入標頭

• :status 標頭會轉換為 number。
• :status、:method、:authority、:scheme、:path、:protocol、age、authorization、access-control-allow-credentials、access-control-max-age、access-control-request-method、content-encoding、content-language、content-length、content-location、content-md5、content-range、content-type、date、dnt、etag、expires、from、host、if-match、if-modified-since、if-none-match、if-range、if-unmodified-since、last-modified、location、max-forwards、proxy-authorization、range、referer、retry-after、tk、upgrade-insecure-requests、user-agent 或 x-content-type-options 的重複項目會捨棄。
• set-cookie 永遠都是陣列。重複項目會加入陣列。
• 對於重複的 cookie 標頭，其值會以「；」連接。
• 對於所有其他標頭，其值會以「，」連接。

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 標頭，此旗標會自動設定。

此屬性也設定為已接收標頭。它會包含所有標記為敏感的標頭名稱，包括自動標記為敏感的標頭。

設定物件#

http2.getDefaultSettings()、http2.getPackedSettings()、http2.createServer()、http2.createSecureServer()、http2session.settings()、http2session.localSettings 和 http2session.remoteSettings API 會傳回或接收輸入物件，其中定義 Http2Session 物件的組態設定。這些物件是包含下列屬性的普通 JavaScript 物件。

• headerTableSize <number> 指定用於標頭壓縮的最大位元組數。允許的最小值為 0。允許的最大值為 2³²-1。預設值：4096。
• enablePush <布林值> 指定 true 如果 HTTP/2 推送串流將被允許在 Http2Session 實例上。預設： true。
• initialWindowSize <數字> 指定串流層級流量控制中 傳送者 的初始視窗大小（以位元組為單位）。允許的最小值為 0。允許的最大值為 2³²-1。預設： 65535。
• maxFrameSize <數字> 指定最大框架酬載的大小（以位元組為單位）。允許的最小值為 16,384。允許的最大值為 2²⁴-1。預設： 16384。
• maxConcurrentStreams <數字> 指定在 Http2Session 上允許的最大並行串流數。沒有預設值，這表示至少理論上，在 Http2Session 中任何時間點都可以同時開啟 2³²-1 個串流。最小值為 0。允許的最大值為 2³²-1。預設： 4294967295。
• maxHeaderListSize <數字> 指定將接受的標頭清單的最大大小（未壓縮八位元組）。允許的最小值為 0。允許的最大值為 2³²-1。預設： 65535。
• maxHeaderSize <數字> maxHeaderListSize 的別名。
• enableConnectProtocol<布林值> 指定由 RFC 8441 定義的「延伸連線協定」是否啟用。此設定只有在由伺服器傳送時才有意義。一旦 enableConnectProtocol 設定已針對特定 Http2Session 啟用，就無法停用。預設值：false。
• customSettings <物件> 指定其他設定，但尚未在 node 和底層函式庫中實作。物件的鍵定義設定類型的數字值（如 [RFC 7540] 所建立的「HTTP/2 設定」登錄檔中所定義），而值則定義設定的實際數字值。設定類型必須是介於 1 到 2^16-1 之間的整數。它不應該是 node 已處理的設定類型，亦即目前應大於 6，儘管這並非錯誤。值必須是介於 0 到 2^32-1 之間的無符號整數。目前最多支援 10 個自訂設定。它只支援傳送設定，或接收在伺服器或用戶端物件的 remoteCustomSettings 選項中指定的設定值。請勿將設定 ID 的 customSettings 機制與原生處理設定的介面混用，以防設定在未來的 node 版本中獲得原生支援。

設定物件上的所有其他屬性都會被忽略。

錯誤處理#

使用 node:http2 模組時可能會出現數種類型的錯誤狀況

當傳入不正確的引數、選項或設定值時，就會發生驗證錯誤。這些錯誤將永遠由同步 throw 報告。

當在不正確的時間嘗試動作時（例如，在串流關閉後嘗試傳送資料），就會發生狀態錯誤。這些錯誤會使用同步 throw 或透過 Http2Stream、Http2Session 或 HTTP/2 Server 物件上的 'error' 事件報告，具體取決於錯誤發生在哪裡和何時。

當 HTTP/2 會話意外失敗時，就會發生內部錯誤。這些錯誤會透過 Http2Session 或 HTTP/2 Server 物件上的 'error' 事件報告。

當違反各種 HTTP/2 協定限制時，就會發生協定錯誤。這些錯誤會使用同步 throw 或透過 Http2Stream、Http2Session 或 HTTP/2 Server 物件上的 'error' 事件報告，具體取決於錯誤發生在哪裡和何時。

標頭名稱和值中的無效字元處理#

HTTP/2 實作對 HTTP 標頭名稱和值中的無效字元套用比 HTTP/1 實作更嚴格的處理。

標頭欄位名稱不區分大小寫，並透過網路傳輸時嚴格作為小寫字串。Node.js 提供的 API 允許標頭名稱設定為混合大小寫字串（例如 Content-Type），但在傳輸時會將其轉換為小寫（例如 content-type）。

標頭欄位名稱只能包含下列一個或多個 ASCII 字元：a-z、A-Z、0-9、!、#、$、%、&、'、*、+、-、.、^、_、`（反引號）、| 和 ~。

在 HTTP 標頭欄位名稱中使用無效字元會導致串流關閉，並報告協定錯誤。

標頭欄位值處理較為寬鬆，但不應包含換行或回車字元，且應限制在 US-ASCII 字元，符合 HTTP 規範的要求。

在客戶端推播串流#

若要在客戶端接收推播串流，請設定 'stream' 事件的監聽器，在 ClientHttp2Session

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

const client = http2.connect('https://127.0.0.1');

client.on('stream', (pushedStream, requestHeaders) => {
  pushedStream.on('push', (responseHeaders) => {
    // Process response headers
  });
  pushedStream.on('data', (chunk) => { /* handle pushed data */ });
});

const req = client.request({ ':path': '/' }); copy

支援 CONNECT 方法#

CONNECT 方法用於允許將 HTTP/2 伺服器用作 TCP/IP 連線的代理伺服器。

一個簡單的 TCP 伺服器

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

const server = net.createServer((socket) => {
  let name = '';
  socket.setEncoding('utf8');
  socket.on('data', (chunk) => name += chunk);
  socket.on('end', () => socket.end(`hello ${name}`));
});

server.listen(8000); copy

一個 HTTP/2 CONNECT 代理伺服器

const http2 = require('node:http2');
const { NGHTTP2_REFUSED_STREAM } = http2.constants;
const net = require('node:net');

const proxy = http2.createServer();
proxy.on('stream', (stream, headers) => {
  if (headers[':method'] !== 'CONNECT') {
    // Only accept CONNECT requests
    stream.close(NGHTTP2_REFUSED_STREAM);
    return;
  }
  const auth = new URL(`tcp://${headers[':authority']}`);
  // It's a very good idea to verify that hostname and port are
  // things this proxy should be connecting to.
  const socket = net.connect(auth.port, auth.hostname, () => {
    stream.respond();
    socket.pipe(stream);
    stream.pipe(socket);
  });
  socket.on('error', (error) => {
    stream.close(http2.constants.NGHTTP2_CONNECT_ERROR);
  });
});

proxy.listen(8001); copy

一個 HTTP/2 CONNECT 客戶端

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

const client = http2.connect('https://127.0.0.1:8001');

// Must not specify the ':path' and ':scheme' headers
// for CONNECT requests or an error will be thrown.
const req = client.request({
  ':method': 'CONNECT',
  ':authority': 'localhost:8000',
});

req.on('response', (headers) => {
  console.log(headers[http2.constants.HTTP2_HEADER_STATUS]);
});
let data = '';
req.setEncoding('utf8');
req.on('data', (chunk) => data += chunk);
req.on('end', () => {
  console.log(`The server says: ${data}`);
  client.close();
});
req.end('Jane'); copy

擴充的 CONNECT 協定#

RFC 8441 定義了 HTTP/2 的「擴充 CONNECT 協定」擴充功能，可用於使用 CONNECT 方法啟動 Http2Stream 的使用，作為其他通訊協定（例如 WebSockets）的通道。

HTTP/2 伺服器透過使用 enableConnectProtocol 設定來啟用擴充 CONNECT 協定的使用

const http2 = require('node:http2');
const settings = { enableConnectProtocol: true };
const server = http2.createServer({ settings }); copy

一旦客戶端從伺服器接收表示可以使用擴充 CONNECT 的 SETTINGS 框架，它就可以傳送使用 ':protocol' HTTP/2 偽標頭的 CONNECT 要求

const http2 = require('node:http2');
const client = http2.connect('https://127.0.0.1:8080');
client.on('remoteSettings', (settings) => {
  if (settings.enableConnectProtocol) {
    const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' });
    // ...
  }
}); copy

相容性 API#

相容性 API 的目標是提供類似於使用 HTTP/2 時的 HTTP/1 開發人員體驗，讓開發人員可以開發同時支援 HTTP/1 和 HTTP/2 的應用程式。此 API 僅針對 HTTP/1 的公開 API。但是，許多模組使用內部方法或狀態，且這些方法或狀態不受支援，因為這是一個完全不同的實作。

下列範例使用相容性 API 建立 HTTP/2 伺服器

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

若要建立混合的 HTTPS 和 HTTP/2 伺服器，請參閱 ALPN 協商 區段。不支援從非 TLS HTTP/1 伺服器升級。

HTTP/2 相容性 API 由 Http2ServerRequest 和 Http2ServerResponse 組成。它們旨在與 HTTP/1 的 API 相容，但不會隱藏通訊協定的差異。例如，會忽略 HTTP 程式碼的狀態訊息。

ALPN 協商#

ALPN 協商允許在同一個 socket 上同時支援 HTTPS 和 HTTP/2。req 和 res 物件可以是 HTTP/1 或 HTTP/2，應用程式必須限制自己使用 HTTP/1 的公開 API，並偵測是否可以使用 HTTP/2 的更進階功能。

下列範例建立同時支援這兩個通訊協定的伺服器

const { createSecureServer } = require('node:http2');
const { readFileSync } = require('node:fs');

const cert = readFileSync('./cert.pem');
const key = readFileSync('./key.pem');

const server = createSecureServer(
  { cert, key, allowHTTP1: true },
  onRequest,
).listen(4443);

function onRequest(req, res) {
  // Detects if it is a HTTPS request or HTTP/2
  const { socket: { alpnProtocol } } = req.httpVersion === '2.0' ?
    req.stream.session : req;
  res.writeHead(200, { 'content-type': 'application/json' });
  res.end(JSON.stringify({
    alpnProtocol,
    httpVersion: req.httpVersion,
  }));
} copy

'request' 事件在 HTTPS 和 HTTP/2 上的運作方式相同。

類別：http2.Http2ServerRequest#

• 延伸：<stream.Readable>

Http2ServerRequest 物件由 http2.Server 或 http2.SecureServer 建立，並作為 'request' 事件的第一個引數傳遞。它可用於存取請求狀態、標頭和資料。

事件：'aborted'#

'aborted' 事件會在 Http2ServerRequest 執行中異常中止時發出。

只有在 Http2ServerRequest 可寫入端尚未結束時，才會發出 'aborted' 事件。

事件：'close'#

表示基礎的 Http2Stream 已關閉。就像 'end' 一樣，此事件只會在每個回應中發生一次。

request.aborted#

• <布林值>

如果請求已中止，request.aborted 屬性會為 true。

request.authority#

• <字串>

請求授權偽標頭欄位。由於 HTTP/2 允許請求設定 :authority 或 host，因此此值會從 req.headers[':authority']（如果存在）衍生而來。否則，會從 req.headers['host'] 衍生而來。

request.complete#

• <布林值>

如果要求已完成、中斷或銷毀，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#

• <字串>

如果是伺服器要求，則為客戶端傳送的 HTTP 版本。如果是客戶端回應，則為已連線伺服器的 HTTP 版本。傳回 '2.0'。

另外，message.httpVersionMajor 是第一個整數，而 message.httpVersionMinor 是第二個整數。

request.method#

• <字串>

以字串表示的要求方法。唯讀。範例：'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#

• <字串>

要求的 scheme 偽標頭欄位，指出目標 URL 的 scheme 部分。

request.setTimeout(msecs, callback)#

• msecs <number>
• callback <函式>
• 傳回：<http2.Http2ServerRequest>

將 Http2Stream 的逾時值設定為 msecs。如果提供了回呼函式，則會將它新增為回應物件上 'timeout' 事件的監聽器。

如果沒有將 'timeout' 監聽器新增到要求、回應或伺服器，則 Http2Stream 會在逾時時銷毀。如果已將處理常式指派給要求、回應或伺服器的 'timeout' 事件，則必須明確處理逾時的 socket。

request.socket#

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

傳回一個作為 net.Socket (或 tls.TLSSocket) 的 Proxy 物件，但會根據 HTTP/2 邏輯套用 getter、setter 和方法。

destroyed、readable 和 writable 屬性會從 request.stream 中擷取並設定到 request.stream。

destroy、emit、end、on 和 once 方法會在 request.stream 上呼叫。

setTimeout 方法會在 request.stream.session 上呼叫。

pause、read、resume 和 write 會擲出具有程式碼 ERR_HTTP2_NO_SOCKET_MANIPULATION 的錯誤。請參閱 Http2Session 和 Sockets 以取得更多資訊。

所有其他互動都會直接路由到 socket。使用 TLS 支援時，請使用 request.socket.getPeerCertificate() 來取得客戶端的驗證詳細資料。

request.stream#

• <Http2Stream>

支援請求的 Http2Stream 物件。

request.trailers#

• <Object>

請求/回應拖曳物件。只會在 'end' 事件中填入。

request.url#

• <字串>

請求 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

類別：http2.Http2ServerResponse#

• 延伸：<Stream>

這個物件是由 HTTP 伺服器在內部建立，而非由使用者建立。它會作為 'request' 事件的第二個參數傳遞。

事件：'close'#

表示在呼叫 response.end() 或能夠執行 flush 之前，底層的 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 <函式>
• 傳回：<this>

此方法會向伺服器發出訊號，表示所有回應標頭和主體都已傳送；伺服器應將此訊息視為已完成。每個回應都必須呼叫 response.end() 方法。

如果指定了 data，則等同於呼叫 response.write(data, encoding)，然後再呼叫 response.end(callback)。

如果指定了 callback，則會在回應串流完成時呼叫它。

response.finished#

• <布林值>

布林值，表示回應是否已完成。從 false 開始。在 response.end() 執行後，值會變為 true。

response.getHeader(name)#

• name <string>
• 傳回：<字串>

讀取已排入佇列但尚未傳送給客戶端的標頭。名稱不區分大小寫。

const contentType = response.getHeader('content-type'); 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 <string>
• 傳回：<boolean>

如果目前在傳送標頭中設定了由 name 識別的標頭，則傳回 true。標頭名稱比對不區分大小寫。

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

response.headersSent#

• <布林值>

如果已傳送標頭，則為 True，否則為 false（唯讀）。

response.removeHeader(name)#

• name <string>

移除已排隊準備隱式傳送的標頭。

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

response.req#

• <http2.Http2ServerRequest>

原始 HTTP2 request 物件的參考。

response.sendDate#

• <布林值>

如果標頭中尚未存在 Date 標頭，則在為 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 <函式>
• 傳回：<http2.Http2ServerResponse>

將 Http2Stream 的逾時值設定為 msecs。如果提供了回呼函式，則會將它新增為回應物件上 'timeout' 事件的監聽器。

如果沒有將 'timeout' 監聽器新增到要求、回應或伺服器，則 Http2Stream 會在逾時時銷毀。如果已將處理常式指派給要求、回應或伺服器的 'timeout' 事件，則必須明確處理逾時的 socket。

response.socket#

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

傳回一個作為 net.Socket (或 tls.TLSSocket) 的 Proxy 物件，但會根據 HTTP/2 邏輯套用 getter、setter 和方法。

destroyed、readable 和 writable 屬性會從 response.stream 中擷取並設定到 response.stream。

destroy、emit、end、on 和 once 方法會在 response.stream 上呼叫。

setTimeout 方法會在 response.stream.session 上呼叫。

pause、read、resume 和 write 會擲出具有程式碼 ERR_HTTP2_NO_SOCKET_MANIPULATION 的錯誤。請參閱 Http2Session 和 Sockets 以取得更多資訊。

所有其他互動都會直接路由到 socket。

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#

• <數字>

當使用隱式標頭（未明確呼叫 response.writeHead()）時，此屬性會控制在標頭被清除時傳送至用戶端的狀態碼。

response.statusCode = 404; copy

在回應標頭傳送至用戶端後，此屬性會指出已傳送出的狀態碼。

response.statusMessage#

• <字串>

HTTP/2（RFC 7540 8.1.2.4）不支援狀態訊息。它會傳回一個空字串。

response.stream#

• <Http2Stream>

支援回應的 Http2Stream 物件。

response.writableEnded#

• <布林值>

在呼叫 response.end() 之後為 true。此屬性並未指出資料是否已快取，若要得知此資訊，請改用 writable.writableFinished。

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

• chunk <string> | <Buffer> | <Uint8Array>
• encoding <string>
• callback <函式>
• 傳回：<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。

收集 HTTP/2 效能指標#

可以使用 效能觀察器 API 為每個 Http2Session 和 Http2Stream 執行個體收集基本效能指標。

const { PerformanceObserver } = require('node:perf_hooks');

const obs = new PerformanceObserver((items) => {
  const entry = items.getEntries()[0];
  console.log(entry.entryType);  // prints 'http2'
  if (entry.name === 'Http2Session') {
    // Entry contains statistics about the Http2Session
  } else if (entry.name === 'Http2Stream') {
    // Entry contains statistics about the Http2Stream
  }
});
obs.observe({ entryTypes: ['http2'] }); copy

PerformanceEntry 的 entryType 屬性將等於 'http2'。

PerformanceEntry 的 name 屬性將等於 'Http2Stream' 或 'Http2Session'。

如果 name 等於 Http2Stream，則 PerformanceEntry 將包含下列其他屬性

• bytesRead <number> 此 Http2Stream 收到的 DATA 框架位元組數。
• bytesWritten <number> 此 Http2Stream 傳送的 DATA 框架位元組數。
• id <number> 關聯的 Http2Stream 識別碼
• timeToFirstByte <number> PerformanceEntry startTime 和收到第一個 DATA 框架之間經過的毫秒數。
• timeToFirstByteSent <number> PerformanceEntry startTime 和傳送第一個 DATA 框架之間經過的毫秒數。
• timeToFirstHeader <數字> PerformanceEntry startTime 與接收第一個標頭之間經過的毫秒數。

如果 name 等於 Http2Session，PerformanceEntry 將包含下列額外屬性

• bytesRead <數字> 接收到的這個 Http2Session 的位元組數。
• bytesWritten <數字> 傳送的這個 Http2Session 的位元組數。
• framesReceived <數字> Http2Session 收到的 HTTP/2 框架數。
• framesSent <數字> Http2Session 傳送的 HTTP/2 框架數。
• maxConcurrentStreams <數字> Http2Session 生命週期中同時開啟的最大串流數。
• pingRTT <數字> 傳送 PING 框架與接收其確認之間經過的毫秒數。僅在 Http2Session 上已傳送 PING 框架時才會存在。
• streamAverageDuration <數字> 所有 Http2Stream 執行個體的平均持續時間（以毫秒為單位）。
• streamCount <數字> Http2Session 處理的 Http2Stream 執行個體數。
• type <字串> 'server' 或 'client'，用於識別 Http2Session 的類型。

關於 :authority 和 host 的注意事項#

HTTP/2 要求要求具有 :authority 偽標頭或 host 標頭。在直接建構 HTTP/2 要求時優先使用 :authority，在從 HTTP/1 轉換時使用 host（例如在代理中）。

如果沒有 :authority，相容性 API 會退回到 host。請參閱 request.authority 以取得更多資訊。但是，如果您不使用相容性 API（或直接使用 req.headers），則需要自己實作任何退回行為。