Node.js 18+ 内置 fetch 无法使用 SOCKS5 代理的解决方案

在开发 Node.js 项目时，我们经常遇到需要通过 SOCKS5 代理访问受限接口的需求。随着 Node.js 18 引入全局 fetch（基于 Undici 实现），开发者原本熟悉的 HTTP Agent 机制失效了。本文将深入剖析为什么 Node 18+ 的内置 fetch 无法直接走 SOCKS5，并提供可行的替代方案。

背景：现代 Node.js 的代理困境

Node.js 18 引入的原生 fetch 接口极大地简化了 HTTP 请求的编写。然而，对于很多开发者来说，fetch 的使用体验并不完美，尤其是当你的网络环境必须依赖 SOCKS5 代理时。

默认情况下，Node.js 的 HTTP 栈（http 和 https 模块）支持通过 globalAgent 配置 SOCKS5。但是，当你使用 fetch 时，它底层调用的是 Undici，这是一个高性能的 HTTP 客户端实现。Undici 采用了与旧版 Node.js 完全不同的架构——Dispatcher 模式。这导致了原本的 SOCKS5 Agent 无法直接作用于 fetch 请求。

为什么内置 fetch 走不通 SOCKS5？

经过多轮测试，我们发现无法通过简单的配置让 Undici 的 fetch 走 SOCKS5，主要原因在于底层协议处理的不兼容。

1. ProxyAgent 协议不支持

Undici 提供了 ProxyAgent，它是专门为 HTTP/HTTPS 代理设计的。

• 尝试代码：setGlobalDispatcher(new ProxyAgent('socks5://127.0.0.1:1080'))
• 结果：Undici 直接拒绝该协议。
• 原因：ProxyAgent 仅实现了 HTTP CONNECT 隧道机制，它不解析 SOCKS5 的握手协议。对于 SOCKS5 这种需要先建立隧道再传输数据的方式，Undici 目前没有内置支持。

2. 环境变量机制失效

通常我们会通过设置环境变量来配置代理。

• 尝试代码：HTTPS_PROXY=socks5://127.0.0.1:1080
• 结果：环境变量被读取，但连接依然失败。
• 原因：Undici 虽然支持读取 HTTPS_PROXY 等环境变量来生成默认 Dispatcher，但它只认 HTTP/HTTPS 协议。它无法识别 socks5:// 这种 URL 格式。

3. global-agent 与 undici 架构不兼容

global-agent 是一个流行的全局代理库。

• 尝试代码：运行 bootstrap() 方法。
• 结果：无法生效。
• 原因：global-agent 的原理是劫持 Node.js 原生的 http.globalAgent 和 https.globalAgent。但是，fetch 的底层逻辑并不直接使用这两个 Agent，而是使用 Undici 的全局 Dispatcher。两者是两条完全平行的技术路线，无法互相覆盖。

4. Agent 对象无法注入 Dispatcher

使用了成熟的 socks-proxy-agent 库。

• 尝试代码：将 socks-proxy-agent 创建的 Agent 传给 fetch。
• 结果：无效。
• 原因：fetch 的第二个参数只接受 Dispatcher 对象，不接受传统的 Agent 对象。而 socks-proxy-agent 只能被 https.request 这种旧接口使用。

实战解决方案：切换 HTTP 栈

既然内置的 fetch 无法直接对接 SOCKS5，目前的最佳实践是针对特定接口切换 HTTP 栈。

推荐方案：axios + socks-proxy-agent

如果你必须使用 SOCKS5，最稳妥的办法是引入 axios 并配合 socks-proxy-agent。

• 优势：axios 对 SOCKS5 的支持非常成熟，开箱即用，无需处理复杂的握手细节。
• 劣势：这会导致你的项目中同时存在两套 HTTP 栈（一套是原生 fetch，一套是 axios）。这意味着你需要维护两套错误处理逻辑和超时设置，增加了代码的维护成本。

代码示例

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

const agent = new SocksProxyAgent('socks5://127.0.0.1:1080');

// 使用 axios 访问接口
const response = await axios.get('https://api.example.com/limited', { httpAgent: agent });

进阶思考：如果坚持用 fetch 怎么办？

如果你非常依赖 fetch 的 API，且不想引入 axios，那么唯一的出路是自己实现一个 Dispatcher。

Undici 要求自定义 Dispatcher 必须实现以下核心方法：

• dispatch：负责发起请求的核心逻辑。
• connect：这是最关键的方法。你需要在这里实现 SOCKS5 的握手协议（包括认证、协商、建立隧道）。普通的 HTTP CONNECT 隧道在这里需要被替换为 SOCKS5 的握手流程。
• connectTimeout：处理连接超时。

目前社区并没有一个非常成熟、专门为 Undici Dispatcher 封装的 SOCKS5 库。开发者通常需要基于 undici 的文档，参考 ProxyAgent 的源码，自己编写或基于 socks-proxy-agent 的逻辑进行移植。

总结

在 Node.js 18+ 环境下，原生 fetch 目前无法直接通过 SOCKS5 代理工作。这是由于 Undici 架构与旧版 HTTP Agent 机制不兼容导致的。对于大多数开发者，建议在特定模块中使用 axios + socks-proxy-agent 作为过渡方案。如果你是框架作者或需要深度集成，则需要自行实现 Undici 的 Dispatcher 接口以支持 SOCKS5 协议。