Gemini CLI 报 HttpsProxyAgent is not a constructor 深度排查与模块解耦

1. Bug 本质：Node.js ESM/CJS 导出的历史断层

在使用 Node.js 开发的 CLI 工具中，网络代理普遍依赖开源库 https-proxy-agent。然而在该库从 5.x 版本向 6.x/7.x 版本演进的过程中，其导出格式经历了重大变革：

当 Gemini CLI 使用 esbuild 或 Webpack 将依赖打包为单个可执行单文件（Bundle）时，如果打包配置中的 ESM 互操作（Interop）参数不严谨，编译产物在运行时实际上获取到的是一个外层包裹对象：

// 开发者预期的结果：
const AgentClass = HttpsProxyAgent; // 是一个 Function / Class

// 实际运行时拿到的对象结构：
const AgentClass = {
  __esModule: true,
  HttpsProxyAgent: class HttpsProxyAgent extends Agent { ... },
  default: class HttpsProxyAgent extends Agent { ... }
};

// 执行以下语句时，直接抛出 TypeError！
const agent = new AgentClass(proxyUrl);
// 报错：TypeError: HttpsProxyAgent is not a constructor

2. 为什么该报错意味着请求“从未离开本机”

许多开发者在遇到该报错时，习惯性地怀疑“是不是梯子挂了”、“是不是端口写错了”或者“Google 账号被风控了”。这些判断都是完全错误的：

• 物理层面未触网：该异常属于 JavaScript 引擎在执行主线程函数时的语法类型错误（TypeError）。此时底层套接字（Socket）根本没有分配，操作系统网卡没有发出任何一个 SYN 数据包。
• 与服务器端点无关：无论你的目标 Base URL 是 Google 官方、Vertex AI 还是第三方中转站，代码在拼装 HTTP Agent 的第 0 步就已崩溃，远端服务器的访问日志中绝对不可能有该请求的记录。

3. 终端验证：进程级环境变量净化与对照实验

要 100% 确认该 Bug 是否由代理环境变量触发，最简单的方法是在当前子进程中临时剔除代理变量，进行对照实验：

# 1. 打印当前残留的代理变量
env | grep -i proxy

# 2. 临时剔除所有代理变量并启动最小请求
env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy gemini --prompt "ping"

在 Windows PowerShell 中，可使用一次性子进程进行验证：

# 临时清空当前会话的代理变量
$env:HTTP_PROXY=""
$env:HTTPS_PROXY=""
$env:http_proxy=""
$env:https_proxy=""

# 再次运行 gemini
gemini --prompt "ping"

若清空变量后 CLI 不再弹出 TypeError，即可铁证证明故障点正是 CLI 内部的代理构造分支。

4. 方案一：开启系统级 TUN 虚拟网卡规避应用层代理

在必须跨国访问官方端点的网络环境下，如果你无法等待官方发布修复版本的 CLI，推荐开启系统级 **TUN（虚拟网卡）模式**：

• TUN 模式会在操作系统内核层创建一个虚拟网络接口（如 utun 或 wintun），接管全操作系统的所有 IP 层流量。
• 开启 TUN 模式后，请**彻底从 .bashrc、.zshrc 或系统变量中删除 HTTP_PROXY 与 HTTPS_PROXY**。
• Gemini CLI 在没有检测到代理环境变量时，会顺畅走 Node.js 原生的 https.Agent 代码分支，完美绕过存在缺陷的第三方代理依赖库；而此时底层 TCP 数据流早已被操作系统透明转发至目标节点。

5. 方案二：架构终极方案——国内专线中转免代理直连

对于大部分国内企业开发团队和个人开发者，依赖本地多层代理客户端不仅容易触发各种运行时的环境 Bug，还会带来严重的网络抖动、DNS 污染和高延迟。

最彻底、最稳定的工业级解法是直接接入词元AI中转聚合网络（统一接入端点：https://api.gpt345.com/v1）：

# 彻底清空所有本地代理配置
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

# 配置词元中转统一端点与长效 API Key
export OPENAI_BASE_URL="https://api.gpt345.com/v1"
export OPENAI_API_KEY="sk-gpt345-enterprise-api-key"

# 享受 100% 原生 HTTPS 专线直通加速
curl https://api.gpt345.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-8-flash",
    "messages": [{"role": "user", "content": "国内专线免梯直连测试"}]
  }'

该架构彻底移除了繁琐的代理中继环路，将调用链路收敛为标准的 TCP/TLS 直连，毫秒级响应，杜绝一切由于 Node 代理库打包不良导致的进程崩溃。

6. 常见问题与排错手册