[社区] Gemini CLI 在 macOS Intel 启动时因 TypeError: fetch failed (undici) 崩溃

问题

在 macOS（Intel，非 Apple Silicon）上运行 gemini 命令时，CLI 启动即崩溃，Debug 控制台（F12）显示：

TypeError: fetch failed
    at node:internal/deps/undici/undici:...

此错误通常发生在 Gemini CLI 启动时的网络握手阶段（检查认证状态或拉取配置），Intel Mac 上的 Node.js/undici 网络行为与 Apple Silicon 存在差异，可能导致此问题。

来源：Stack Overflow #79776595

解决方案

方案 1：升级 Gemini CLI 到最新版本（最优先）

社区和官方对此类问题的首要修复建议是更新版本：

npm install -g @google/gemini-cli@latest
gemini --version

多数 Intel Mac 崩溃问题已在后续版本修复。

方案 2：检查 Node.js 版本（最常见原因）

undici 的 fetch 在旧版 Node.js（v18 以下）上行为不稳定：

node --version  # 确认版本

推荐使用 Node.js v20 LTS 或 v22：

# 使用 nvm 切换
nvm install 20
nvm use 20
npm install -g @google/gemini-cli

方案 3：设置环境变量禁用证书验证（临时排查用）

用于确认是否为 SSL/TLS 证书问题（不建议长期使用）：

export NODE_TLS_REJECT_UNAUTHORIZED=0
gemini

如果设置后能正常启动，说明是网络证书问题，应检查公司代理或系统根证书。

方案 4：检查代理设置

如果你在有网络代理的环境下工作，确认代理配置对 Node.js 生效：

export HTTPS_PROXY=http://your-proxy:port
export HTTP_PROXY=http://your-proxy:port
gemini

常见问题

Q: 为什么同样的 Gemini CLI 版本在 Apple Silicon Mac 上正常，Intel Mac 上崩溃？

A: Intel 和 Apple Silicon 使用不同的 Node.js 构建版本，undici 的底层网络实现对 CPU 架构有差异。升级到最新 Node.js LTS 可以减少这类差异。

Q: 清理缓存是否有帮助？

A: 部分用户报告清理浏览器缓存（用于 OAuth 流程的 Chrome）并重新安装 CLI 可以解决认证相关的崩溃。值得一试：npm uninstall -g @google/gemini-cli && npm install -g @google/gemini-cli。

Q: 卸载后重装还是崩溃怎么办？

A: 检查是否存在多个 Node.js 版本冲突：which node && node --version，确保 npm global 安装使用的 Node.js 是你期望的版本。