Node.js 代理设置：环境变量、fetch、axios 和 SOCKS5

通过环境变量使用内置支持

Node.js 的 HTTP 文档介绍了内置的代理支持：读取 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 变量（大小写均可）。它默认不开启，需要用 NODE_USE_ENV_PROXY=1 变量或 --use-env-proxy 参数打开，文档把它标为 Stability 1.1，即仍在积极开发。NODE_USE_ENV_PROXY 变量在 Node.js v24.0.0 和 v22.21.0 中加入，--use-env-proxy 参数和 http.Agent 的 proxyEnv 选项在 v24.5.0 和 v22.21.0 中加入；更早的版本会忽略这个变量。开启后，它对 fetch() 从 v24.0.0 和 v22.21.0 起生效，对通过全局 agent 发出的 http.request() 和 https.request() 从 v24.5.0 和 v22.21.0 起生效，所以在 v24.0.0 到 v24.4.x 上它只作用于 fetch()。

文档里写的代理 URL 格式是 http:// 和 https://，账号密码写成 http://username:password@host:port。所以这个内置支持针对 HTTP 代理，不包括 SOCKS5。

通过环境变量使用内置支持：示例

NODE_USE_ENV_PROXY=1 \
HTTPS_PROXY="http://USERNAME:[email protected]:2222" \
node app.js

请把 USERNAME 和 PASSWORD 换成「我的资产」里的值。如果要请求普通的 http:// 地址，也要设置 HTTP_PROXY。

通过环境变量使用内置支持（续）

文档还介绍了可以在代码里用 http.setGlobalProxyFromEnv()（24.14.0 和 25.4.0 起提供）打开这项支持。Node.js 说明，内置代理支持不是匿名功能，代理能看到连接的元数据，所以只使用你信任的代理。

• 来源：
• Node.js 文档：HTTP，内置代理支持
• Node.js 文档：命令行选项 --use-env-proxy

用 undici ProxyAgent 给 fetch 设代理

安装 undici 包，把 ProxyAgent 作为 dispatcher 传给 fetch。最新的 undici 文档写明，ProxyAgent 会让请求通过 HTTP、HTTPS 或 SOCKS5 代理（请确认你安装的 undici 版本支持 socks5: 开头的 URL；下面的示例用的是 HTTP 端口），并且代理 URL 里的账号密码在使用前会做 URL 解码。

用 undici ProxyAgent 给 fetch 设代理：示例

import { ProxyAgent, fetch } from 'undici'

const user = encodeURIComponent('USERNAME')
const pass = encodeURIComponent('PASSWORD')
const dispatcher = new ProxyAgent(`http://${user}:${pass}@proxy.proxy302.com:2222`)

const res = await fetch('https://ipinfo.io/json', { dispatcher })
console.log(await res.json())

给密码编码，是为了保护 @、: 和 / 这类会破坏 URL 的字符。

• 来源：
• undici 文档：ProxyAgent
• MDN：encodeURIComponent()

axios

axios 文档允许在请求里设置 proxy 对象，包含 protocol、host、port 和 auth（账号和密码）。目标是 https:// 地址时，axios 1.16.1 及更新版本会通过代理建立 CONNECT 隧道；1.16.0 及更早的版本里，Node 的 http 适配器会把请求按明文转发的方式直接发给 HTTP 代理，不建立隧道，也没有端到端 TLS，所以请先升级 axios（1.17.0 起，隧道里还会保留你自己 httpsAgent 的 TLS 设置）。如果代理本身使用 HTTPS，要把 protocol 设为 https；Proxy302 的 HTTP 端口 2222 要把 protocol 设为 http。

axios：示例

import axios from 'axios'

const res = await axios.get('https://ipinfo.io/json', {
  proxy: {
    protocol: 'http',
    host: 'proxy.proxy302.com',
    port: 2222,
    auth: { username: 'USERNAME', password: 'PASSWORD' },
  },
})
console.log(res.data)

proxy 对象里账号和密码是分开的字段，所以不需要做 URL 编码。

• 来源：
• axios 文档：请求配置中的 proxy

代理 agent，包括 SOCKS5

proxy-agents 项目为内置的 http 和 https 模块提供 http.Agent 类。https-proxy-agent 连接 HTTP 或 HTTPS 代理，使用 CONNECT 方法；socks-proxy-agent 连接 SOCKS 代理。在这两个包的源代码里，都会从代理 URL 读取账号和密码并做 URL 解码，socks-proxy-agent 接受 socks4、socks4a、socks5 和 socks5h 几种写法。

代理 agent，包括 SOCKS5：示例

import https from 'node:https'
import { SocksProxyAgent } from 'socks-proxy-agent'

const agent = new SocksProxyAgent(
  `socks5h://${encodeURIComponent('USERNAME')}:${encodeURIComponent('PASSWORD')}@proxy.proxy302.com:3333`
)
https.get('https://ipinfo.io/json', { agent }, (res) => res.pipe(process.stdout))

用 socks5h 时由代理解析域名。Proxy302 的 SOCKS5 在 3333 端口；用 HTTP 代理时请换成 HttpsProxyAgent 和 2222 端口。

• 来源：
• proxy-agents 项目：https-proxy-agent 和 socks-proxy-agent

检查出口

像上面每个示例那样，通过代理请求 https://ipinfo.io/json。country 和 org 字段应该描述的是代理，而不是你自己的网络。如果结果是你自己的地址，说明这次请求没有走代理：检查变量是不是在 Node 启动前设置的，或者 agent、dispatcher 有没有传给这次调用。各字段含义见代理位置检查指南。

• 代理位置检查指南

常见错误

按 Node.js 的错误列表，ECONNREFUSED 表示目标机器主动拒绝了连接，通常是因为那里没有服务在运行：检查地址和端口。ETIMEDOUT 表示对方在一段时间内没有正常响应：检查端口、你的网络和设置的超时。ENOTFOUND 是 DNS 查询失败：检查域名。状态码 407 表示代理没有接受账号密码，见代理认证失败指南。还要确认协议与端口相符：HTTP 用 2222，SOCKS5 用 3333；代理连接失败指南里有逐项检查。

• 代理认证失败指南
• 代理连接失败指南

• 来源：
• Node.js 文档：常见系统错误

用 Proxy302 怎么做

上面任何一种客户端，只需要 Proxy302 代理的地址、端口、账号和密码。动态住宅按流量计费，出口国家在生成代理时设置；HTTP 在 proxy.proxy302.com 的 2222 端口，SOCKS5 在 3333 端口。静态 ISP IP 在整个租期内固定，不轮换。下表是我们最近一次每小时检测时 7 个国家的出口；探测器请求的是 ChatGPT，它只是网络检测用的示例目标。代理不会改变 ChatGPT 的服务条款，OpenAI 公布的支持国家和地区名单仍然适用，见 ChatGPT、Claude、Gemini 支持哪些国家和地区。详情见动态住宅页面和代理位置检查指南。

• 动态住宅页面
• 代理位置检查指南
• ChatGPT、Claude、Gemini 支持哪些国家和地区

实测出口：ChatGPT 从 7 个国家的连通

Proxy302 探测器每小时检测一次，本次检测时间：2026 年 10 月 25 日 08:29 UTC。每个国家通过一个动态住宅出口、经公开的 Proxy302 入口向 ChatGPT 发一次请求。IP 只公开前三段。每国一个样本，不是平均值，之后的检测结果会不同。

• 来源：
• Proxy302 每小时连通检测

用 Proxy302 怎么做：步骤

1. 第 1 步

   打开动态住宅页面，选择线路，「协议」保持 HTTP 或改选 SOCKS5，然后点击「确认费用并生成」。

2. 第 2 步

   打开「我的资产」（控制台里放着你买到的全部代理），复制 HOST（地址）、PORT（端口）、USERNAME（账号）和 PASSWORD（密码）。「连接工具」页（控制台里教你把代理接到各种软件的页面）里有填好你自己连接信息的现成示例。

3. 第 3 步

   把这些信息填入你正在设置的浏览器或软件。

4. 第 4 步

   通过代理访问 https://ipinfo.io/json 确认出口。

5. 第 5 步

   在中国大陆，先在「连接工具」页打开辅助工具，使用代理期间保持开着。

   • 辅助工具指南

价格与限制

低价线路每 GB 收费 US$1.50，100 GB 套餐每 GB US$1.35，300 GB 每 GB US$1.20。不提供免费试用，最小购买单位为 1 GB。可用的出口位置每天都会变化。

• 来源：
• Proxy302 产品事实与价格表

常见问题

延伸阅读

代理的地址、端口、账号和密码怎么填

每个可用的代理都由五个基本字段构成：协议、地址、端口、账号和密码。

407 代理需要认证怎么办

HTTP 407 来自代理服务器，而不是你要访问的网站。

代理连接失败怎么排查

Chrome 或 Edge 连不上代理服务器时，会显示 ERR_PROXY_CONNECTION_FAILED，完整提示是「无法连接到代理服务器」。

代理 IP 怎么查：IP 地址、国家、运营商

30 秒查清代理的 IP、国家和运营商；为什么不同查询网站城市对不上、纯净度分数看什么。附我们对三家查询服务的实测。