Node.js 的 fetch 为什么不走 HTTPS_PROXY?undici、axios 和 SOCKS5 的正确接法

4 阅读3分钟

利益相关:我在 Proxy302 工作。下面的写法和具体哪家的代理无关,都在 Node 24 上用一个带用户名密码的测试代理跑过。

先说结论: Node 自带的 fetch 默认不读 HTTPS_PROXY 环境变量,设了也会直连。要让它走代理,有三条路:

  1. 用 npm 装的 undici,把 ProxyAgent 作为 dispatcher 传给 同一个包里的 fetch;
  2. Node 24(以及 22.21 以后)启动时加 NODE_USE_ENV_PROXY=1,内置 fetch 就会照环境变量走;
  3. 用 axios 的话,给它一个 https-proxy-agent 的 agent,同时写上 proxy: false。

SOCKS5 用 socks-proxy-agent,地址写 socks5h://,让域名也在代理那边解析。

坑一:环境变量设了,出口还是本机

很多人从 curl、Python 过来,习惯 export HTTPS_PROXY=... 就完事。Node 的内置 fetch 不这样:不加开关,它完全忽略这个变量。最省事的验证办法是打印出口 IP:

HTTPS_PROXY="http://USER:PASS@HOST:PORT" node -e "fetch('https://api.ipify.org').then(r=>r.text()).then(console.log)"
# 打印的是本机公网 IP

HTTPS_PROXY="http://USER:PASS@HOST:PORT" NODE_USE_ENV_PROXY=1 node -e "fetch('https://api.ipify.org').then(r=>r.text()).then(console.log)"
# 打印的是代理的出口 IP

Node 24.5 以后也可以用命令行参数 --use-env-proxy 代替这个环境变量。

坑二:把 npm 的 ProxyAgent 塞给内置 fetch

内置 fetch 底层也是 undici,于是有人这样写:

import { ProxyAgent } from 'undici';
const res = await fetch(url, { dispatcher: new ProxyAgent(PROXY) }); // 内置 fetch

npm 装的 undici 和 Node 内置的 undici 版本不同,我们测的时候直接报 invalid onRequestStart method。改成从同一个包里取 fetch:

import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent('http://USER:PASS@HOST:PORT');
const res = await fetch('https://ipinfo.io/json', { dispatcher });
console.log(res.status, (await res.json()).ip);

想让进程里所有请求都按环境变量走(包括 NO_PROXY),用 EnvHttpProxyAgent 设成全局:

import { setGlobalDispatcher, EnvHttpProxyAgent, fetch } from 'undici';

setGlobalDispatcher(new EnvHttpProxyAgent()); // 读 HTTP_PROXY、HTTPS_PROXY、NO_PROXY
console.log(await (await fetch('https://api.ipify.org')).text());

坑三:axios 套了两层代理

axios 自己有 proxy 选项,也会读环境变量。如果再给它一个 agent,环境里又刚好设了 HTTPS_PROXY,两套代理逻辑就会叠在一起,排查起来很绕。用 agent 时把它自己的关掉:

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://USER:PASS@HOST:PORT');
const { data } = await axios.get('https://ipinfo.io/json', {
  httpsAgent: agent,
  proxy: false,
  timeout: 30000,
});
console.log(data.ip);

坑四:SOCKS5 的域名在本机解析了

socks5:// 是本机先把域名解析成 IP 再交给代理,socks5h:// 是把域名交给代理去解析。前者在 DNS 被污染或者需要按代理所在地解析时会出问题,一般都用后者:

import axios from 'axios';
import { SocksProxyAgent } from 'socks-proxy-agent';

const agent = new SocksProxyAgent('socks5h://USER:PASS@HOST:PORT');
const { data } = await axios.get('https://ipinfo.io/json', {
  httpAgent: agent,
  httpsAgent: agent,
  proxy: false,
});
console.log(data.ip);

坑五:轮换代理却一直是同一个出口

按连接换 IP 的动态代理,只有新开连接时才换出口。agent 默认保持长连接,连续请求同一个网站会复用同一条隧道,所以出口一直不变。要每次换,就每次新建 agent,或者在请求头里带 Connection: close;要保持同一个出口做多步操作,反而应该复用。

常见报错对照

现象多半是
出口还是本机 IP内置 fetch 没加 NODE_USE_ENV_PROXY=1
invalid onRequestStart methodnpm 的 ProxyAgent 传给了内置 fetch
407用户名或密码错,密码里有 @、: 要先 encodeURIComponent
axios 出口和预期不一致agent 和 axios 自己的 proxy 或环境变量叠在一起,没写 proxy: false
轮换代理出口不变长连接被复用

写完记得用打印出口 IP 的那两行跑一遍,确认请求真的走了代理再上线。