企业网络配置

¥Enterprise Network Configuration

概述

¥Overview

企业环境通常要求应用在企业代理后运行，并使用自定义证书颁发机构 (CA) 进行 SSL/TLS 验证。Node.js 通过环境变量和命令行标志内置支持这些要求，在许多情况下无需使用第三方代理库。

¥Enterprise environments often require applications to operate behind corporate proxies and use custom certificate authorities (CAs) for SSL/TLS validation. Node.js provides built-in support for these requirements through environment variables and command-line flags, eliminating the need for third-party proxy libraries in many cases.

本指南介绍了如何配置 Node.js 应用以在企业网络环境中运行：

¥This guide covers how to configure Node.js applications to work in enterprise network environments:

• 通过 NODE_USE_ENV_PROXY 环境变量或 --use-env-proxy 标志配置代理

  ¥Configuring proxies via the NODE_USE_ENV_PROXY environment variable or the --use-env-proxy flag

• 通过 NODE_USE_SYSTEM_CA 环境变量或 --use-system-ca 标志从系统证书存储中添加证书颁发机构。

  ¥Adding certificate authorities from system store via the NODE_USE_SYSTEM_CA environment variable or the --use-system-ca flag.

代理配置

¥Proxy Configuration

在许多企业环境中，出于安全和监控的考虑，对外部服务的互联网访问可能需要通过 HTTP/HTTPS 代理进行路由。这要求应用在发送网络请求时能够感知并使用这些代理。

¥In many enterprise environments, internet access to external services may need to be routed through HTTP/HTTPS proxies for security and monitoring. This requires applications to be aware of and use these proxies when making network requests.

代理设置通常通过环境变量（例如 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY）提供。启用 NODE_USE_ENV_PROXY 或 --use-env-proxy 时，Node.js 支持这些证书。此功能适用于 node:http 和 node:https（v22.21.0 或 v24.5.0+）方法以及 fetch()（v22.21.0 或 v24.0.0+）。

¥Proxy settings are often provided via environment variables such as HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. Node.js supports these when NODE_USE_ENV_PROXY or --use-env-proxy is enabled. This works with node:http and node:https (v22.21.0 or v24.5.0+) methods as well as fetch() (v22.21.0 or v24.0.0+).

示例（POSIX shell）：

¥Example (POSIX shells):

# The proxy settings might be configured in the system by your IT department
# and shared across different tools.
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

# To enable it for Node.js applications.
export NODE_USE_ENV_PROXY=1
node app.js

或者，你也可以在 Node.js v22.21.0 或 v24.5.0 及更高版本中使用命令行标志 --use-env-proxy 启用此功能：

¥Alternatively, enable it via the command-line flag --use-env-proxy on Node.js v22.21.0 or v24.5.0 and above:

# The proxy settings might be configured in the system by your IT department
# and shared across different tools.
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

# To enable it for Node.js applications.
node --use-env-proxy app.js

或者，如果使用 --env-file 从文件中加载环境变量：

¥Or, if --env-file is used to load environment variables from a file:

# In .env file
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1,.company.com
NODE_USE_ENV_PROXY=1

启用后，http、https 和 fetch() 请求默认使用已配置的代理，除非代理被覆盖或目标匹配 NO_PROXY。

¥Once enabled, http, https, and fetch() requests use the configured proxies by default, unless an agent is overridden or the target matches NO_PROXY.

以编程方式配置代理

¥Configure the Proxy Programmatically

要以编程方式配置代理，请覆盖代理。目前 https.request() 及其衍生方法（例如 https.get()）支持此功能。

¥To configure the proxy programmatically, override the agents. This is currently supported by https.request() and other methods built upon it such as https.get().

要逐个请求地覆盖代理，请使用 agent 选项对 http.request()/https.request() 以及类似方法进行设置：

¥To override the agent on a per-request basis, use the agent option for http.request()/https.request() and similar methods:

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

// Creating a custom agent with custom proxy support.
const agent = new https.Agent({
  proxyEnv: { HTTPS_PROXY: 'http://proxy.company.com:8080' },
});

https.request(
  {
    hostname: 'www.external.com',
    port: 443,
    path: '/',
    agent,
  },
  res => {
    // This request will be proxied through proxy.company.com:8080 using the HTTP protocol.
  }
);

要全局覆盖代理，请重置 http.globalAgent 和 https.globalAgent：

¥To override the agent globally, reset http.globalAgent and https.globalAgent:

注意：全局代理不会影响 fetch()。

¥Note: Global agents do not affect fetch().

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

http.globalAgent = new http.Agent({
  proxyEnv: { HTTP_PROXY: 'http://proxy.company.com:8080' },
});
https.globalAgent = new https.Agent({
  proxyEnv: { HTTPS_PROXY: 'http://proxy.company.com:8080' },
});

// Subsequent requests will all use the configured proxies, unless they override the agent option.
http.request('http://external.com', res => {
  /* ... */
});
https.request('https://external.com', res => {
  /* ... */
});

使用代理进行身份验证

¥Using Proxies with Authentication

如果代理需要身份验证，请在代理 URL 中包含凭据：

¥If the proxy requires authentication, include credentials in the proxy URL:

export HTTPS_PROXY=http://username:password@proxy.company.com:8080

安全提示：避免在环境变量文件中提交凭据。建议使用密钥管理器和程序化配置。

¥Security Note: Avoid committing credentials in env files. Prefer a secret manager and programmatic configuration.

代理绕过配置

¥Proxy Bypass Configuration

NO_PROXY 变量支持：

¥The NO_PROXY variable supports:

• * - 绕过所有主机的代理

  ¥* - Bypass proxy for all hosts

• company.com - 精确主机名匹配

  ¥company.com - Exact host name match

• .company.com - 域名后缀匹配（匹配 sub.company.com）

  ¥.company.com - Domain suffix match (matches sub.company.com)

• *.company.com - 通配符域名匹配

  ¥*.company.com - Wildcard domain match

• 192.168.1.100 - 精确 IP 地址匹配

  ¥192.168.1.100 - Exact IP address match

• 192.168.1.1-192.168.1.100 - IP 地址范围

  ¥192.168.1.1-192.168.1.100 - IP address range

• company.com:8080 - 指定端口的主机名

  ¥company.com:8080 - Hostname with specific port

如果目标匹配 NO_PROXY，则请求将绕过代理。

¥If a target matches NO_PROXY, the request bypasses the proxy.

证书颁发机构配置

¥Certificate Authority Configuration

默认情况下，Node.js 使用 Mozilla 打包的根 CA，而不会查询操作系统证书存储。在许多企业环境中，内部 CA 证书安装在操作系统证书存储区中，并且在连接到内部服务时需要信任这些证书；连接到由这些 CA 签名的证书可能会验证失败，并出现如下错误：

¥By default, Node.js uses Mozilla’s bundled root CAs and does not consult the OS store. In many enterprise environments, internal CAs are installed in the OS store and are expected to be trusted when connecting to internal services; connections to certificates signed by those CAs can fail validation with errors such as:

Error: self signed certificate in certificate chain

从 Node.js v22.15.0、v23.9.0、v24.0.0 及更高版本开始，Node.js 可以配置为使用系统证书存储区信任这些自定义 CA。

¥From Node.js v22.15.0, v23.9.0, v24.0.0 and above, Node.js can be configured to trust these custom CAs using the system's certificate store.

从系统存储添加 CA 证书

¥Adding CA Certificates from the System Store

• 通过环境变量：NODE_USE_SYSTEM_CA=1 node app.js

  ¥From environment variable: NODE_USE_SYSTEM_CA=1 node app.js

• 通过命令行标志：node --use-system-ca app.js

  ¥From command-line flag: node --use-system-ca app.js

启用后，Node.js 会加载系统 CA，并将其与自带 CA 一起使用进行 TLS 验证。

¥When enabled, Node.js loads system CAs and uses them in addition to its bundled CAs for TLS validation.

Node.js 根据平台从不同位置读取证书：

¥Node.js reads certificates from different locations depending on the platform:

• Windows：Windows 证书存储（通过 Windows Crypto API）

  ¥Windows: Windows Certificate Store (via Windows Crypto API)

• macOS：macOS 密钥串

  ¥macOS: macOS Keychain

• Linux：OpenSSL 默认设置通常通过 SSL_CERT_FILE/SSL_CERT_DIR 或 /etc/ssl/cert.pem 和 /etc/ssl/certs/ 等路径（取决于 OpenSSL 版本）提供。

  ¥Linux: OpenSSL defaults, typically via SSL_CERT_FILE/SSL_CERT_DIR, or paths like /etc/ssl/cert.pem and /etc/ssl/certs/ depending on the OpenSSL build

Node.js 遵循与 Chromium 类似的策略。有关详细信息，请参阅 Node.js 文档。

¥Node.js follows a policy similar to that of Chromium. See the Node.js documentation for more details.

添加其他 CA 证书

¥Adding additional CA Certificates

要添加特定的 CA 证书而不依赖系统证书存储：

¥To add specific CA certificates without relying on the system store:

export NODE_EXTRA_CA_CERTS=/path/to/company-ca-bundle.pem
node app.js

该文件应包含一个或多个 PEM 编码的证书。

¥The file should contain one or more PEM-encoded certificates.

组合选项

¥Combining Options

你可以将 NODE_USE_SYSTEM_CA 与 NODE_EXTRA_CA_CERTS 结合使用：

¥You can combine NODE_USE_SYSTEM_CA with NODE_EXTRA_CA_CERTS:

export NODE_USE_SYSTEM_CA=1
export NODE_EXTRA_CA_CERTS=/path/to/additional-cas.pem
node app.js

启用后，Node.js 将信任打包的 CA、系统 CA 以及 NODE_EXTRA_CA_CERTS 指定的其他证书。

¥With both enabled, Node.js trusts bundled CAs, system CAs, and the additional certificates specified by NODE_EXTRA_CA_CERTS.

以编程方式配置 CA 证书

¥Configure CA Certificates Programmatically

配置全局 CA 证书

¥Configure Global CA Certificates

使用 tls.getCACertificates() 和 tls.setDefaultCACertificates() 配置全局 CA 证书。例如，要将系统证书添加到默认证书存储区：

¥Use tls.getCACertificates() and tls.setDefaultCACertificates() to configure global CA certificates. For example, to add system certificates into the default store:

const https = require('node:https');
const tls = require('node:tls');
const currentCerts = tls.getCACertificates('default');
const systemCerts = tls.getCACertificates('system');
tls.setDefaultCACertificates([...currentCerts, ...systemCerts]);

// Subsequent requests use system certificates during verification.
https.get('https://internal.company.com', res => {
  /* ... */
});
fetch('https://internal.company.com').then(res => {
  /* ... */
});

为单个请求配置 CA 证书

¥Configure CA Certificates for Individual Requests

要为每个请求覆盖 ​​CA 证书，请使用 ca 选项。目前仅 tls.connect()/https.request() 及其衍生方法（例如 https.get()）支持此功能。

¥To override CA certificates per request, use the ca option. This is currently only supported by tls.connect()/https.request() and methods built upon them such as https.get().

const https = require('node:https');
const specialCerts = ['-----BEGIN CERTIFICATE-----\n...'];
https.get(
  {
    hostname: 'internal.company.com',
    port: 443,
    path: '/',
    method: 'GET',
    // The `ca` option replaces defaults; concatenate bundled certs if needed.
    ca: specialCerts,
  },
  res => {
    /* ... */
  }
);