企业网络配置

🌐 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 标志配置代理
• 通过 NODE_USE_SYSTEM_CA 环境变量或 --use-system-ca 标志从系统存储添加证书颁发机构。

代理配置

🌐 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

启用后，除非指定了代理或目标匹配 NO_PROXY，否则 http、https 和 fetch() 请求默认使用配置的代理。

🌐 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().

要在每个请求级别覆盖代理，请在 http.request()/https.request() 及类似方法中使用 agent 选项：

🌐 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()。

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

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

代理绕过配置

🌐 Proxy Bypass Configuration

NO_PROXY 变量支持：

🌐 The NO_PROXY variable supports:

• * - 对所有主机绕过代理
• company.com - 精确主机名匹配
• .company.com - 域名后缀匹配（匹配 sub.company.com）
• *.company.com - 通配符域名匹配
• 192.168.1.100 - 精确 IP 地址匹配
• 192.168.1.1-192.168.1.100 - IP 地址范围
• company.com:8080 - 带有特定端口的主机名

如果目标匹配 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
• 来自命令行标志：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 加密 API）
• macOS：macOS 钥匙串
• Linux：OpenSSL 的默认设置，通常通过 SSL_CERT_FILE/SSL_CERT_DIR，或根据 OpenSSL 构建的不同使用像 /etc/ssl/cert.pem 和 /etc/ssl/certs/ 这样的路径

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 => {
    /* ... */
  }
);