Node.js v20.18.0 文档

确定加密支持是否不可用#

¥Determining if crypto support is unavailable

可以在不支持 node:crypto 模块的情况下构建 Node.js。在这种情况下，尝试 import https 或调用 require('node:https') 将导致抛出错误。

¥It is possible for Node.js to be built without including support for the node:crypto module. In such cases, attempting to import from https or calling require('node:https') will result in an error being thrown.

使用 CommonJS 时，可以使用 try/catch 捕获抛出的错误：

¥When using CommonJS, the error thrown can be caught using try/catch:

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

当使用词法 ESM import 关键字时，只有在尝试加载模块（例如，使用预加载模块）之前注册了 process.on('uncaughtException') 的处理程序时，才能捕获错误。

¥When using the lexical ESM import keyword, the error can only be caught if a handler for process.on('uncaughtException') is registered before any attempt to load the module is made (using, for instance, a preload module).

使用 ESM 时，如果有可能在未启用加密支持的 Node.js 版本上运行代码，则考虑使用 import() 函数而不是 import 关键字：

¥When using ESM, if there is a chance that the code may be run on a build of Node.js where crypto support is not enabled, consider using the import() function instead of the lexical import keyword:

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

类：https.Agent#

¥Class: https.Agent

HTTPS 的 Agent 对象，类似于 http.Agent。有关详细信息，请参阅 https.request()。

¥An Agent object for HTTPS similar to http.Agent. See https.request() for more information.

new Agent([options])#

• options <Object> 要在代理上设置的可配置选项集。可以具有与 http.Agent(options) 相同的字段，以及

  ¥options <Object> Set of configurable options to set on the agent. Can have the same fields as for http.Agent(options), and

  • maxCachedSessions <number> TLS 缓存会话的最大数量。使用 0 禁用 TLS 会话缓存。默认值：100。

    ¥maxCachedSessions <number> maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: 100.

  • servername <string> 要发送到服务器的 服务器名称指示扩展 的值。使用空字符串 '' 禁用发送扩展名。默认值：目标服务器的主机名，除非使用 IP 地址指定目标服务器，在这种情况下，默认值为 ''（无扩展名）。

    ¥servername <string> the value of Server Name Indication extension to be sent to the server. Use empty string '' to disable sending the extension. Default: host name of the target server, unless the target server is specified using an IP address, in which case the default is '' (no extension).

    有关 TLS 会话重用的信息，请参阅会话恢复。

    ¥See Session Resumption for information about TLS session reuse.

事件：'keylog'#

¥Event: 'keylog'

• line <Buffer> ASCII 文本行，采用 NSS SSLKEYLOGFILE 格式。

  ¥line <Buffer> Line of ASCII text, in NSS SSLKEYLOGFILE format.

• tlsSocket <tls.TLSSocket> 生成它的 tls.TLSSocket 实例。

  ¥tlsSocket <tls.TLSSocket> The tls.TLSSocket instance on which it was generated.

当此代理管理的连接生成或接收密钥材料时（通常在握手完成之前，但不一定），则会触发 keylog 事件。该密钥材料可以存储用于调试，因为它允许对捕获的 TLS 流量进行解密。它可以为每个套接字多次触发。

¥The keylog event is emitted when key material is generated or received by a connection managed by this agent (typically before handshake has completed, but not necessarily). This keying material can be stored for debugging, as it allows captured TLS traffic to be decrypted. It may be emitted multiple times for each socket.

一个典型的用例是将接收到的行附加到公共文本文件中，稍后软件（例如 Wireshark）使用它来解密流量：

¥A typical use case is to append received lines to a common text file, which is later used by software (such as Wireshark) to decrypt the traffic:

// ...
https.globalAgent.on('keylog', (line, tlsSocket) => {
  fs.appendFileSync('/tmp/ssl-keys.log', line, { mode: 0o600 });
}); 拷贝

类：https.Server#

¥Class: https.Server

• 继承：<tls.Server>

  ¥Extends: <tls.Server>

有关详细信息，请参阅 http.Server。

¥See http.Server for more information.

server.close([callback])#

• callback <Function>

• 返回：<https.Server>

  ¥Returns: <https.Server>

参见 node:http 模块中的 server.close()。

¥See server.close() in the node:http module.

server[Symbol.asyncDispose]()#

调用 server.close() 并返回一个在服务器关闭时履行的 promise。

¥Calls server.close() and returns a promise that fulfills when the server has closed.

server.closeAllConnections()#

参见 node:http 模块中的 server.closeAllConnections()。

¥See server.closeAllConnections() in the node:http module.

server.closeIdleConnections()#

参见 node:http 模块中的 server.closeIdleConnections()。

¥See server.closeIdleConnections() in the node:http module.

server.headersTimeout#

• <number> 默认值：60000

  ¥<number> Default: 60000

参见 node:http 模块中的 server.headersTimeout。

¥See server.headersTimeout in the node:http module.

server.listen()#

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

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

server.maxHeadersCount#

• <number> 默认值：2000

  ¥<number> Default: 2000

参见 node:http 模块中的 server.maxHeadersCount。

¥See server.maxHeadersCount in the node:http module.

server.requestTimeout#

• <number> 默认值：300000

  ¥<number> Default: 300000

参见 node:http 模块中的 server.requestTimeout。

¥See server.requestTimeout in the node:http module.

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

• msecs <number> 默认值：120000（2 分钟）

  ¥msecs <number> Default: 120000 (2 minutes)

• callback <Function>

• 返回：<https.Server>

  ¥Returns: <https.Server>

参见 node:http 模块中的 server.setTimeout()。

¥See server.setTimeout() in the node:http module.

server.timeout#

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

  ¥<number> Default: 0 (no timeout)

参见 node:http 模块中的 server.timeout。

¥See server.timeout in the node:http module.

server.keepAliveTimeout#

• <number> 默认值：5000（5 秒）

  ¥<number> Default: 5000 (5 seconds)

参见 node:http 模块中的 server.keepAliveTimeout。

¥See server.keepAliveTimeout in the node:http module.

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

• options <Object> 接受来自 tls.createServer()、tls.createSecureContext() 和 http.createServer() 的 options。

  ¥options <Object> Accepts options from tls.createServer(), tls.createSecureContext() and http.createServer().

• requestListener <Function> 要添加到 'request' 事件的监听器。

  ¥requestListener <Function> A listener to be added to the 'request' event.

• 返回：<https.Server>

  ¥Returns: <https.Server>

// curl -k https://localhost:8000/
import { createServer } from 'node:https';
import { readFileSync } from 'node:fs';

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

createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);// curl -k https://localhost:8000/
const https = require('node:https');
const fs = require('node:fs');

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

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);拷贝

或者

¥Or

import { createServer } from 'node:https';
import { readFileSync } from 'node:fs';

const options = {
  pfx: readFileSync('test_cert.pfx'),
  passphrase: 'sample',
};

createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);const https = require('node:https');
const fs = require('node:fs');

const options = {
  pfx: fs.readFileSync('test_cert.pfx'),
  passphrase: 'sample',
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(8000);拷贝

要为此示例生成证书和密钥，则运行：

¥To generate the certificate and key for this example, run:

openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout private-key.pem -out certificate.pem 拷贝

然后，要为此示例生成 pfx 证书，请运行：

¥Then, to generate the pfx certificate for this example, run:

openssl pkcs12 -certpbe AES-256-CBC -export -out test_cert.pfx \
  -inkey private-key.pem -in certificate.pem -passout pass:sample 拷贝

https.get(options[, callback])#

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

• url <string> | <URL>

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

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

• callback <Function>

类似于 http.get()，但用于 HTTPS。

¥Like http.get() but for HTTPS.

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

¥options can be an object, a string, or a URL object. If options is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

import { get } from 'node:https';
import process from 'node:process';

get('https://encrypted.google.com/', (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });

}).on('error', (e) => {
  console.error(e);
});const https = require('node:https');

https.get('https://encrypted.google.com/', (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });

}).on('error', (e) => {
  console.error(e);
});拷贝

https.globalAgent#

所有 HTTPS 客户端请求的 https.Agent 全局实例。与默认 https.Agent 配置不同，启用了 keepAlive 且 timeout 为 5 秒。

¥Global instance of https.Agent for all HTTPS client requests. Diverges from a default https.Agent configuration by having keepAlive enabled and a timeout of 5 seconds.

https.request(options[, callback])#

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

• url <string> | <URL>

• options <Object> | <string> | <URL> 接受来自 http.request() 的所有 options，默认值有一些不同：

  ¥options <Object> | <string> | <URL> Accepts all options from http.request(), with some differences in default values:

  • protocol 默认值：'https:'

    ¥protocol Default: 'https:'

  • port 默认值：443

    ¥port Default: 443

  • agent 默认值：https.globalAgent

    ¥agent Default: https.globalAgent

• callback <Function>

• 返回：<http.ClientRequest>

  ¥Returns: <http.ClientRequest>

触发请求到安全的 Web 服务器。

¥Makes a request to a secure web server.

tls.connect() 中的以下附加 options 也被接受：ca、cert、ciphers、clientCertEngine（已弃用）、crl、dhparam、ecdhCurve、honorCipherOrder、key、passphrase、pfx、rejectUnauthorized、secureOptions、secureProtocol、servername、sessionIdContext、highWaterMark。

¥The following additional options from tls.connect() are also accepted: ca, cert, ciphers, clientCertEngine (deprecated), crl, dhparam, ecdhCurve, honorCipherOrder, key, passphrase, pfx, rejectUnauthorized, secureOptions, secureProtocol, servername, sessionIdContext, highWaterMark.

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

¥options can be an object, a string, or a URL object. If options is a string, it is automatically parsed with new URL(). If it is a URL object, it will be automatically converted to an ordinary options object.

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

¥https.request() returns an instance of the http.ClientRequest class. The ClientRequest instance is a writable stream. If one needs to upload a file with a POST request, then write to the ClientRequest object.

import { request } from 'node:https';
import process from 'node:process';

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
};

const req = request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (e) => {
  console.error(e);
});
req.end();const https = require('node:https');

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
};

const req = https.request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  console.log('headers:', res.headers);

  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (e) => {
  console.error(e);
});
req.end();拷贝

使用 tls.connect() 中的选项的示例：

¥Example using options from tls.connect():

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('private-key.pem'),
  cert: fs.readFileSync('certificate.pem'),
};
options.agent = new https.Agent(options);

const req = https.request(options, (res) => {
  // ...
}); 拷贝

或者，通过不使用 Agent 来选择退出连接池。

¥Alternatively, opt out of connection pooling by not using an Agent.

const options = {
  hostname: 'encrypted.google.com',
  port: 443,
  path: '/',
  method: 'GET',
  key: fs.readFileSync('private-key.pem'),
  cert: fs.readFileSync('certificate.pem'),
  agent: false,
};

const req = https.request(options, (res) => {
  // ...
}); 拷贝

使用 URL 作为 options 的示例：

¥Example using a URL as options:

const options = new URL('https://abc:xyz@example.com');

const req = https.request(options, (res) => {
  // ...
}); 拷贝

固定证书指纹或公钥（类似于 pin-sha256）的示例：

¥Example pinning on certificate fingerprint, or the public key (similar to pin-sha256):

import { checkServerIdentity } from 'node:tls';
import { Agent, request } from 'node:https';
import { createHash } from 'node:crypto';

function sha256(s) {
  return createHash('sha256').update(s).digest('base64');
}
const options = {
  hostname: 'github.com',
  port: 443,
  path: '/',
  method: 'GET',
  checkServerIdentity: function(host, cert) {
    // Make sure the certificate is issued to the host we are connected to
    const err = checkServerIdentity(host, cert);
    if (err) {
      return err;
    }

    // Pin the public key, similar to HPKP pin-sha256 pinning
    const pubkey256 = 'SIXvRyDmBJSgatgTQRGbInBaAK+hZOQ18UmrSwnDlK8=';
    if (sha256(cert.pubkey) !== pubkey256) {
      const msg = 'Certificate verification error: ' +
        `The public key of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // Pin the exact certificate, rather than the pub key
    const cert256 = 'FD:6E:9B:0E:F3:98:BC:D9:04:C3:B2:EC:16:7A:7B:' +
      '0F:DA:72:01:C9:03:C5:3A:6A:6A:E5:D0:41:43:63:EF:65';
    if (cert.fingerprint256 !== cert256) {
      const msg = 'Certificate verification error: ' +
        `The certificate of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // This loop is informational only.
    // Print the certificate and public key fingerprints of all certs in the
    // chain. Its common to pin the public key of the issuer on the public
    // internet, while pinning the public key of the service in sensitive
    // environments.
    let lastprint256;
    do {
      console.log('Subject Common Name:', cert.subject.CN);
      console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);

      const hash = createHash('sha256');
      console.log('  Public key ping-sha256:', sha256(cert.pubkey));

      lastprint256 = cert.fingerprint256;
      cert = cert.issuerCertificate;
    } while (cert.fingerprint256 !== lastprint256);

  },
};

options.agent = new Agent(options);
const req = request(options, (res) => {
  console.log('All OK. Server matched our pinned cert or public key');
  console.log('statusCode:', res.statusCode);

  res.on('data', (d) => {});
});

req.on('error', (e) => {
  console.error(e.message);
});
req.end();const tls = require('node:tls');
const https = require('node:https');
const crypto = require('node:crypto');

function sha256(s) {
  return crypto.createHash('sha256').update(s).digest('base64');
}
const options = {
  hostname: 'github.com',
  port: 443,
  path: '/',
  method: 'GET',
  checkServerIdentity: function(host, cert) {
    // Make sure the certificate is issued to the host we are connected to
    const err = tls.checkServerIdentity(host, cert);
    if (err) {
      return err;
    }

    // Pin the public key, similar to HPKP pin-sha256 pinning
    const pubkey256 = 'SIXvRyDmBJSgatgTQRGbInBaAK+hZOQ18UmrSwnDlK8=';
    if (sha256(cert.pubkey) !== pubkey256) {
      const msg = 'Certificate verification error: ' +
        `The public key of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // Pin the exact certificate, rather than the pub key
    const cert256 = 'FD:6E:9B:0E:F3:98:BC:D9:04:C3:B2:EC:16:7A:7B:' +
      '0F:DA:72:01:C9:03:C5:3A:6A:6A:E5:D0:41:43:63:EF:65';
    if (cert.fingerprint256 !== cert256) {
      const msg = 'Certificate verification error: ' +
        `The certificate of '${cert.subject.CN}' ` +
        'does not match our pinned fingerprint';
      return new Error(msg);
    }

    // This loop is informational only.
    // Print the certificate and public key fingerprints of all certs in the
    // chain. Its common to pin the public key of the issuer on the public
    // internet, while pinning the public key of the service in sensitive
    // environments.
    do {
      console.log('Subject Common Name:', cert.subject.CN);
      console.log('  Certificate SHA256 fingerprint:', cert.fingerprint256);

      hash = crypto.createHash('sha256');
      console.log('  Public key ping-sha256:', sha256(cert.pubkey));

      lastprint256 = cert.fingerprint256;
      cert = cert.issuerCertificate;
    } while (cert.fingerprint256 !== lastprint256);

  },
};

options.agent = new https.Agent(options);
const req = https.request(options, (res) => {
  console.log('All OK. Server matched our pinned cert or public key');
  console.log('statusCode:', res.statusCode);

  res.on('data', (d) => {});
});

req.on('error', (e) => {
  console.error(e.message);
});
req.end();拷贝

示例的输出：

¥Outputs for example:

Subject Common Name: github.com
  Certificate SHA256 fingerprint: FD:6E:9B:0E:F3:98:BC:D9:04:C3:B2:EC:16:7A:7B:0F:DA:72:01:C9:03:C5:3A:6A:6A:E5:D0:41:43:63:EF:65
  Public key ping-sha256: SIXvRyDmBJSgatgTQRGbInBaAK+hZOQ18UmrSwnDlK8=
Subject Common Name: Sectigo ECC Domain Validation Secure Server CA
  Certificate SHA256 fingerprint: 61:E9:73:75:E9:F6:DA:98:2F:F5:C1:9E:2F:94:E6:6C:4E:35:B6:83:7C:E3:B9:14:D2:24:5C:7F:5F:65:82:5F
  Public key ping-sha256: Eep0p/AsSa9lFUH6KT2UY+9s1Z8v7voAPkQ4fGknZ2g=
Subject Common Name: USERTrust ECC Certification Authority
  Certificate SHA256 fingerprint: A6:CF:64:DB:B4:C8:D5:FD:19:CE:48:89:60:68:DB:03:B5:33:A8:D1:33:6C:62:56:A8:7D:00:CB:B3:DE:F3:EA
  Public key ping-sha256: UJM2FOhG9aTNY0Pg4hgqjNzZ/lQBiMGRxPD5Y2/e0bw=
Subject Common Name: AAA Certificate Services
  Certificate SHA256 fingerprint: D7:A7:A0:FB:5D:7E:27:31:D7:71:E9:48:4E:BC:DE:F7:1D:5F:0C:3E:0A:29:48:78:2B:C8:3E:E0:EA:69:9E:F4
  Public key ping-sha256: vRU+17BDT2iGsXvOi76E7TQMcTLXAqj0+jGPdW7L1vM=
All OK. Server matched our pinned cert or public key
statusCode: 200 拷贝