集成阅读约 8 分钟

Axios 代理设置：路由、认证与 NO_PROXY

在 Node.js 中为 Axios 配置代理，把显式设置与环境变量路由、agent 路由区分开来，并用可下载的本地实验复现身份认证与 TLS 检查。

作者： ipvolt审校于 以 Markdown 阅读 ↗阅读英文原文
本页内容

在 Node.js 中使用 Axios 时，先从 HTTP 适配器和显式的 proxy 对象开始。把代理凭据放在 proxy.auth 中，验证路由，然后再添加环境变量或自定义 agent。这些层可能改变连接：在我们的本地测试中，当自定义的 Node agent 配置了 proxyEnv 时，proxy: false 仍然走了代理。

本指南使用 Axios 1.20.0 和 Node.js 24.20.0。其中的 15 个路由用例和 4 项配方检查都是基于回环地址的合成测试，并不是对外部代理服务的测量。浏览器中的 Axios 和 Axios 的 fetch 适配器是不同的路径；proxy 选项属于 Node 的 HTTP 适配器。参见 Axios 配置和固定版本的 HTTP 适配器。

运行一次显式的代理检查

把 proxy-check.mjs、package.json 和 lockfile 一起使用。在一个新目录中，使用 Node 24.20.0 或 Node 24 系列中更新的版本：

sh
for file in package.json package-lock.json proxy-check.mjs; do
  curl --fail --silent --show-error \
    "https://ipvolt.com/downloads/axios-proxy-setup/$file" -o "$file" || exit 1
done
npm ci --ignore-scripts --no-audit --no-fund

让你的密钥管理工具提供 PROXY_HOST、PROXY_PORT、PROXY_USER 和 PROXY_PASSWORD，然后运行 node proxy-check.mjs。PROXY_HOST 是不带协议和凭据的主机名。PROXY_PROTOCOL 默认为 http；只有在供应商文档明确提供 TLS 代理端点时才使用 https。它描述的是到代理的连接，而不是到目标的连接。不要把真实密码写进 shell 历史记录或编码代理的提示词里。

检查脚本用相互独立的凭据字段构建如下配置：

js
const proxy = {
  protocol: process.env.PROXY_PROTOCOL || 'http',
  host: process.env.PROXY_HOST,
  port: Number(process.env.PROXY_PORT),
  auth: {
    username: process.env.PROXY_USER,
    password: process.env.PROXY_PASSWORD,
  },
};

这段摘录展示的是配置的形状；可下载的脚本会校验输入并发出请求。它选择 adapter: 'http'，禁用重定向，把响应限制在 4 KiB 以内，并设置了 5 秒的 Axios 超时和 6 秒的中止信号。它会检查返回的 JSON 是否包含有效的 IP 地址，并且只打印结果、状态以及 IP 或错误代码。它不会打印 Axios 的原始错误或请求配置，因为其中可能包含凭据。

运行脚本时，默认会通过你的代理向第三方的 ipify IPv4 JSON 端点发送一个请求。该服务会看到请求的公网源地址。可以把 CHECK_URL 设置为一个不含凭据的 HTTPS 地址，指向经批准且返回相同 { "ip": "..." } 形状的端点。观察到的 IP 只是一次路由检查；它不能验证国家、运营商、住宅分类或性能保证。我们是用受控的本地响应测试检查脚本的，而不是用公开的 ipify。

发送给普通 HTTP 代理的 Basic 凭据，并不会仅仅因为目标是 HTTPS 就在客户端到代理的连接上被加密。在支持的情况下使用 TLS 代理端点，并保持证书验证开启。这个实验测试的是通过 HTTP 代理建立隧道访问受信任的 HTTPS 源站；它没有测试到代理本身的 TLS 传输。

选择由哪一层负责路由

这些观察结果来自固定版本的测试夹具，并且禁用了原生环境代理的启动标志。“直连”表示夹具中的代理什么都没有收到；“走代理”表示它记录到了请求或 CONNECT。原始结果保留了这些观察记录。

配置观察到的路由需要检查什么
HTTP 适配器，显式 proxy，存在冲突的环境变量和 NO_PROXY显式代理从这里开始，得到一个可复现的基线。
HTTP 适配器，没有显式代理，匹配的 HTTP_PROXY 或 HTTPS_PROXY环境变量代理除了应用代码，还要检查进程环境。
由环境变量选定的代理，匹配的 NO_PROXY 条目直连仅凭请求成功并不能证明用了代理。
proxy: false，普通 agent直连在这种情况下，Axios 的环境变量选择被禁用。
普通的自定义 http.Agent，没有显式代理Axios 环境变量代理提供 agent 并不会自动去掉 Axios 对环境变量的处理。
自定义 http.Agent({ proxyEnv: ... })，加上 proxy: falseagent 的代理路由仍然由 agent 控制。
fetch 适配器，Axios 的 proxy 对象直连HTTP 适配器的选项不会配置这个适配器。

对于由环境变量驱动的路由，HTTP_PROXY 适用于 HTTP 目标，HTTPS_PROXY 适用于 HTTPS 目标。值中的协议描述的仍然是代理：HTTPS_PROXY=http://gateway:port 可以为 HTTPS 目标选择一个 HTTP 代理。环境变量指南解释了继承关系。现有的 NO_PROXY 矩阵涵盖的是它自己列出的客户端和版本，而不是这次 Axios 实验。

原生 agent 那一行，是“false 会禁用代理”这种笼统理解的例外。Node 内置的代理支持可以让 agent 拥有自己的路由配置。在夹具中，proxy: false 加上那个 agent 仍然使用了它的代理；把它换成普通 agent 后，对照请求变成了直连。我们没有测试所有启动标志或第三方 agent。请检查传给你的进程的 agent，而不要把 Axios 的某个设置当作对整个网络的保证。

对于 Node 原生的 fetch，请使用 Undici dispatcher 指南。Axios 的 proxy 对象和 fetch 的 dispatcher 是不同的接口。

HTTPS 与认证：找出出错的那一层

Axios 1.20.0 的 HTTP 适配器为实验中的 HTTPS 目标建立了 CONNECT 隧道。受信任的本地 CA 让请求得以通过；去掉这份信任后出现了 DEPTH_ZERO_SELF_SIGNED_CERT。在证书被拒绝的用例中，代理看到了 CONNECT，但 HTTPS 源站没有收到任何应用请求。“Axios 总是需要一个单独的隧道包”这种说法并不符合这个被测试的版本。

代理凭据使用 proxy.auth；Axios 顶层的 auth 是针对目标的认证。在 CONNECT 成功的用例中，夹具的源站没有收到 Proxy-Authorization 标头。代理是在建立隧道这一步收到该凭据的。这一结论只适用于被测试的配置，不适用于任意的拦截代理或重定向。

错误的凭据在普通 HTTP 用例和检查脚本的 HTTPS CONNECT 用例中都产生了状态 407 和代码 ERR_BAD_REQUEST。被拒绝的 CONNECT 到达了代理，但没有产生对源站的请求。Axios 的原始错误可能包含带有凭据的配置：请保留经过清理的代码和可用的状态，而不要记录整个对象。

观察结果下一步检查
代理什么都没收到，而目标请求成功显式设置与继承设置、NO_PROXY、所选的适配器，以及路由由哪个 agent 控制。
代理拒绝认证网关、认证方式和账号范围；参照 407 指南。
CONNECT 成功，随后证书验证失败源站的信任链和主机名；保持 TLS 验证开启。
请求到达了停滞的源站并超时请求的截止时间和源站行为；更长的超时并不能确定原因。
HTTP 200 但响应体不符合预期在接受这次检查之前先校验响应的形状。

停滞的 HTTP 源站在夹具 100 ms 的超时下产生了 ECONNABORTED。这确认的是一条本地失败分支，而不是有用的生产环境超时或延迟基准。可复用的检查脚本使用更长的有界截止时间，并且从不自动重试。

复现路由矩阵

把 lab.mjs 下载到检查脚本和固定版本的包文件旁边，然后运行：

sh
curl --fail --silent --show-error \
  https://ipvolt.com/downloads/axios-proxy-setup/lab.mjs -o lab.mjs
node lab.mjs local-results.json

README 记录了前置条件和各个用例。夹具需要 OpenSSL，会绑定随机的 IPv4 回环端口，生成临时的本地证书，并使用虚构的凭据。请先取消原生环境代理的启动标志；测试程序会拒绝这些标志，因为它们会改变它的基线。安装依赖时会访问包注册表；夹具的请求则始终停留在回环地址上。

记录于 2026 年 9 月 28 日，环境为 Node 24.20.0、Axios 1.20.0 和 macOS arm64：15 个路由用例和 4 项配方检查全部通过。这些检查涵盖路由、认证、受信任和不受信任的本地 HTTPS、适配器的作用范围、超时、有效的 IP 输出以及对意外响应体的拒绝。它们不衡量供应商的库存、匿名性、地理位置或吞吐量，也不测试 SOCKS、浏览器中的 Axios、重定向或到代理的 TLS 传输。更换 Axios、Node、适配器或 agent 之后，请重新运行夹具。

如果想在编码代理中获得可选的诊断帮助，Proxy Toolkit MCP 接受经过清理的错误描述。不要把凭据和私有 URL 放进它的参数里，并用一个有界的请求来验证它建议的修改。

ipvolt 的代理访问尚未开放。了解何时开放访问。开放访问时发一封邮件。仅此而已。

参考来源与延伸阅读

本指南参考的技术资料。请以你所安装版本的文档以及代理服务商支持的配置为准。

全部指南