Node.js SOCKS5代理怎么配置？用 Undici 分清接入、DNS 与连接池

Node.js SOCKS5代理接入，常见误区是把 HTTP 代理的环境变量、http.Agent 示例或浏览器配置直接搬进 fetch()。SOCKS5 是独立协议；在 Node.js 中，能否生效取决于请求客户端是否提供 SOCKS5 dispatcher，以及这个 dispatcher 是否真的传给了当前请求。

本文以 Undici 的 Socks5ProxyAgent 为例，只用于企业出口、自有接口和已获授权的网络访问。代理改变的是传输路径，不会改变目标服务的账号权限、频率限制或使用规则。

先确认版本与调用栈

运行前记录 Node.js 和 Undici 版本：

node -v
npm ls undici

Undici 官方把 Socks5ProxyAgent 标为实验性功能，因此生产环境应锁定依赖版本并做升级回归。2026 年公开安全公告还披露过 SOCKS5 多目标连接池路由和 requestTls 传递问题：7.x 应至少使用 7.28.0，8.x 若依赖自定义 TLS 参数应至少使用 8.5.0。不要只看“能连通”，还要确认依赖不在已知受影响区间。

用单请求 dispatcher 完成最小接入

先安装与当前 Node.js 兼容、且已修复相关安全问题的 Undici 版本。把主机、端口和凭据放在受控环境变量中，不要硬编码进仓库：

import { fetch, Socks5ProxyAgent } from 'undici';

const required = [
  'PROXY_HOST',
  'PROXY_PORT',
  'PROXY_USERNAME',
  'PROXY_PASSWORD',
  'HEALTHCHECK_URL',
];

for (const name of required) {
  if (!process.env[name]) throw new Error(`Missing ${name}`);
}

const proxyUrl = new URL(
  `socks5://${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`,
);

const dispatcher = new Socks5ProxyAgent(proxyUrl, {
  username: process.env.PROXY_USERNAME,
  password: process.env.PROXY_PASSWORD,
  connections: 5,
});

try {
  const response = await fetch(process.env.HEALTHCHECK_URL, {
    dispatcher,
    signal: AbortSignal.timeout(10_000),
  });
  console.log({ status: response.status });
} finally {
  await dispatcher.close();
}

把 dispatcher 直接放在单次请求上，影响范围最清楚。只有当整个进程的所有 Undici 请求都应走同一代理时，才考虑 setGlobalDispatcher()；全局设置会影响其他模块，初始化顺序和回退方式必须写进部署记录。

DNS 与 HTTPS 要分别验收

Undici 的 SOCKS5 实现会把目标主机名交给代理解析。这能避免“本地先解析、代理再连接另一个地址”的口径混乱，但也意味着代理侧 DNS 异常时，本机 nslookup 正常仍可能请求失败。验收时准备一个自有域名和一个固定 IP 端点：域名失败、IP 成功时，优先检查代理侧解析和域名策略。

访问 HTTPS 目标时，TLS 在 SOCKS5 隧道内与目标端点协商。不要为了排障设置 rejectUnauthorized: false。若业务使用内部 CA、客户端证书或特定 servername，应通过 requestTls 明确配置，并确认 Undici 版本已经修复相关安全公告；证书链失败应单独处理，不能归因于“代理 IP 不可用”。

用四组对照定位失败阶段

上线前固定目标、超时和请求量，只改变一个变量，依次运行：直连访问自有健康检查、无认证 SOCKS5、正确认证 SOCKS5、错误认证 SOCKS5。记录状态码、总耗时、脱敏出口标识和错误 cause.code，不要记录完整代理 URL、授权头或响应敏感数据。

若连接代理主机时报 ECONNREFUSED 或 ETIMEDOUT，检查地址、端口、防火墙和协议；若握手阶段提示认证失败，核对当前订单凭据或白名单；若健康检查成功而业务返回 401、403、429，应停止扩大请求，回到业务授权与频率规则。基础字段可参考代理IP地址和端口配置指南，出口核验可结合代理IP验证方法。

连接池要有容量、边界和回收

Socks5ProxyAgent 会按目标来源管理连接池。connections 不应直接等于任务并发：先用小值压测，观察代理通道上限、目标响应时间和队列等待，再逐步增加。任务退出时调用 close()；紧急终止才使用 destroy()。代理资源切换后也应创建新的 dispatcher，避免旧连接继续从原出口发送请求。

Node.js SOCKS5代理能稳定运行的关键，不是多写一个代理 URL，而是让协议、Undici 版本、dispatcher 作用域、代理侧 DNS、TLS 与连接池都可验证。需要选择 HTTP(S) 或 SOCKS5 接入、固定或轮换出口时，可查看悟空代理官网当前公开说明，并以实际订单能力与接口文档为准。