结论先说：Node.js 新版本可用 --use-env-proxy 或 NODE_USE_ENV_PROXY=1，让默认 HTTP Agent 与内置 fetch 读取 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY；旧版本或自定义网络库则要按客户端单独设置 Dispatcher/Agent。先确认 Node 版本和请求库，再配置代理，不能只看到环境变量存在就认定请求已经走代理。
本文更新于 2026 年 8 月 24 日，面向已获得网络与目标系统授权的开发、测试和企业接入场景。软件版本、平台规则与供应商能力会变化，上线前请核对官方文档，并在测试环境完成回归。
Node.js 代理配置路径对比
| 路径 | 适用范围 | 优点 | 主要检查点 |
|---|---|---|---|
| --use-env-proxy | 支持该功能的 Node.js 进程 | 启动参数清晰、便于部署审计 | 确认版本与启动命令 |
| NODE_USE_ENV_PROXY=1 | 进程默认 Agent 与内置 fetch | 适合容器和服务环境变量 | 变量需在进程启动前设置 |
| http.setGlobalProxyFromEnv() | 运行时显式启用 | 代码中可见并可恢复 | 注意对全局请求的影响 |
| 自定义 Agent/Dispatcher | 单个客户端或单类请求 | 范围最小、控制精细 | 库之间接口不通用 |
先确认版本：原生代理支持不是所有 Node.js 都一样
Node.js 官方文档显示，内置代理支持加入于 v24.5.0 和 v22.21.0，目前仍标记为“Active development”。这意味着生产环境不能照抄新版本示例后跳过版本检查。先执行 node -v，再确认应用使用的是内置 fetch、node:http，还是 Axios、got、undici 等独立客户端。
如果业务在旧版 LTS 上，环境变量可能被某些库读取，也可能完全不生效。正确做法是查看该库的官方代理接口，并用出口 IP 与请求日志做验证，而不是把升级或关闭 TLS 校验当作第一反应。
推荐配置：把代理参数注入进程，不写进源码
在 Linux/macOS 中可把变量注入单次进程：
HTTP_PROXY=http://user:pass@proxy.example:8000 \
HTTPS_PROXY=http://user:pass@proxy.example:8000 \
NO_PROXY=localhost,127.0.0.1,.internal.example \
node --use-env-proxy app.jsWindows PowerShell 可先设置 $env:HTTP_PROXY、$env:HTTPS_PROXY、$env:NO_PROXY，再启动 Node。不要把真实账号密码提交到 Git、Dockerfile、CI 日志或错误追踪系统；优先使用密钥管理服务或运行时 Secret 注入。
NO_PROXY 怎么写：先保证内网和回环地址不绕路
NO_PROXY 用逗号分隔直连目标。官方文档列出了精确域名、域名后缀、通配符、IP、IP 段和“主机:端口”等格式。基础项通常应包含 localhost、127.0.0.1，并按实际情况加入内部 API、数据库网关和健康检查地址。
上线前制作三组测试：必须代理的外部域名、必须直连的内部域名、容易误匹配的相似域名。记录每组的出口、状态码和耗时。NO_PROXY=* 会让全部主机绕过代理，只适合临时诊断，不应误留在生产配置。
鉴权、特殊字符和 TLS 错误怎么排查
- 407：代理没有接受当前凭据，检查
Proxy-Authenticate、账号、密码、白名单和协议。 - 特殊字符：用户名或密码放进 URL 时要正确进行百分号编码，避免
@、:、#被当作分隔符。 - 证书错误：先区分目标站证书、HTTPS 代理入口证书和企业 TLS 检查证书；不要长期设置
NODE_TLS_REJECT_UNAUTHORIZED=0。 - 超时：分别记录连接代理、建立 CONNECT 隧道、TLS 握手和首字节时间。
上线验收：证明“这个请求”确实经过预期出口
- 记录 Node 版本、启动参数和生效的变量名称，但对凭据脱敏。
- 通过已授权的出口查询接口验证公网 IP，并与供应商分配值比较。
- 对一个必须直连的内部地址和一个必须代理的外部地址分别测试。
- 连续采样可用率、TTFB 与出口漂移，避免只测一次。
- 关闭代理后重复请求，确认失败或出口变化符合预期，排除系统级代理干扰。
如果只有浏览器正常而 Node.js 失败，通常说明两者读取的代理层不同；如果 HTTP 正常而 HTTPS 失败，优先检查 CONNECT、证书和目标端口策略。
常见问题（FAQ）
Node.js 设置 HTTPS_PROXY 后，HTTP 请求也会走代理吗？
不应猜测。HTTP_PROXY 与 HTTPS_PROXY 分别对应不同目标协议，具体还受 Node 版本、客户端库和 NO_PROXY 影响，应逐类实测。
内置 fetch 会自动读取环境变量吗？
在支持内置代理的版本中，还需要用 --use-env-proxy、NODE_USE_ENV_PROXY=1 或相关 API 启用；旧版和第三方库行为不同。
可以把代理密码写在 .env 文件吗？
.env 仍是明文文件。至少要禁止提交版本库、限制文件权限，并在生产中优先使用 Secret 管理与短期凭据。
为什么出口查询正常，业务 API 仍然失败？
出口正确只证明路由生效。还需检查目标 API 权限、TLS、DNS、速率限制、区域可用性和请求参数。