利益相关:我在 Proxy302 工作。下面的写法和具体哪家的代理无关,都在 Node 24 上用一个带用户名密码的测试代理跑过。
先说结论: Node 自带的 fetch 默认不读 HTTPS_PROXY 环境变量,设了也会直连。要让它走代理,有三条路:
- 用 npm 装的
undici,把ProxyAgent作为dispatcher传给 同一个包里的fetch; - Node 24(以及 22.21 以后)启动时加
NODE_USE_ENV_PROXY=1,内置fetch就会照环境变量走; - 用 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 method | npm 的 ProxyAgent 传给了内置 fetch |
| 407 | 用户名或密码错,密码里有 @、: 要先 encodeURIComponent |
| axios 出口和预期不一致 | agent 和 axios 自己的 proxy 或环境变量叠在一起,没写 proxy: false |
| 轮换代理出口不变 | 长连接被复用 |
写完记得用打印出口 IP 的那两行跑一遍,确认请求真的走了代理再上线。