Undici 项目中的代理支持与循环依赖问题解析

背景介绍

Undici 是 Node.js 生态中一个高性能的 HTTP/1.1 客户端库，被设计用来替代 Node.js 核心模块中的 http 模块。近期在项目使用过程中，开发者发现当尝试将 Undici 与 Rollup 打包工具一起使用时，出现了两个主要问题：循环依赖警告和意外的 node:sqlite 模块引入。

问题分析

循环依赖问题

在 Undici 的代码结构中，存在以下循环引用路径：

websocket/util.js → websocket/connection.js → websocket/util.js

这种循环依赖虽然不会影响运行时的功能，但会导致打包工具（如 Rollup）发出警告，并可能影响构建过程的优化。项目维护者迅速响应，在 Pull Request #4006 中修复了这个问题，通过重构代码结构消除了循环依赖。

意外的 node:sqlite 引入

另一个问题是 Rollup 打包时错误地将 Node.js 核心模块 node:sqlite 包含在最终打包文件中。经过分析，这实际上是 Rollup 工具本身的问题，与 Undici 无关。Undici 作为专为 Node.js 环境设计的库，理应像其他核心模块（如 node:events 或 node:http）一样被正确处理。

代理支持优化讨论

在问题讨论过程中，开发者提出了一个更深层次的需求：如何优雅地为 Node.js 的 fetch 实现添加代理支持。当前解决方案需要显式引入 Undici 并配置 ProxyAgent，但这会导致最终打包体积显著增加（约 500KB）。

项目维护者提出了一个建设性的改进方向：Undici 应该内置对代理环境的自动检测支持。具体来说，当检测到 HTTP_PROXY 或 HTTPS_PROXY 环境变量时，自动使用 EnvHttpProxyAgent，否则回退到默认的 Agent 实现。这种改进将：

1. 简化开发者体验，无需显式配置代理
2. 保持向后兼容性
3. 仅在需要时加载代理相关代码

技术实现建议

要实现这一改进，只需在 global.js 中将当前的：

setGlobalDispatcher(new Agent())

替换为：

setGlobalDispatcher(new EnvHttpProxyAgent())

EnvHttpProxyAgent 内部已经实现了环境变量检测逻辑，能够根据环境自动决定是否使用代理，因此这种修改既简单又安全。

总结

Undici 项目展现了开源社区高效的问题响应能力，从发现问题到提出解决方案的整个过程体现了技术深度和用户关怀。对于开发者而言，理解这些底层机制有助于：

1. 更好地诊断打包工具相关问题
2. 评估不同技术方案的权衡取舍
3. 参与开源项目贡献，推动生态改进

未来随着代理支持的自动化和 Node.js 核心对代理功能的原生支持，这类问题的解决将变得更加优雅和高效。