[社区] Gemini CLI 认证登录失败：auth login 卡住或报错

问题

执行 gemini auth login 完成 Google OAuth 授权后，CLI 仍然报认证失败，常见错误信息：

• Error authenticating: Error: When using the Gemini API, you must specify the GEMINI_API_KEY environment variable.
• 浏览器跳转到 localhost 回调地址但页面显示无法访问，CLI 挂起
• 登录成功后立即又提示"未认证"

来源：GitHub Issue #13266、Issue #17225

解决方案

方案一：清除浏览器缓存后重新认证（最有效）

浏览器中遗留的旧 OAuth token 或缓存可能干扰新的认证流程：

1. 在浏览器中清除所有 Google 相关的 Cookie 和缓存数据
2. 退出 Gemini CLI 认证状态：

   gemini auth logout

3. 重新登录：

   gemini auth login

方案二：卸载重装最新版本

旧版本的认证模块可能有 bug，完全重装可解决：

# 卸载旧版本
npm uninstall -g @google/gemini-cli

# 同时清除 npx 缓存（如有用过 npx 方式）
rm -rf "$(npm config get cache)/_npx"

# 安装最新版本
npm install -g @google/gemini-cli@latest

# 重新认证
gemini auth login

方案三：在无头环境（远程服务器/容器）中登录

如果是在 GitHub Codespaces、远程 SSH 或 Docker 容器中使用，浏览器无法弹出，登录流程会失败。此场景只能使用 API Key：

export GEMINI_API_KEY=你的APIKey
gemini

或写入配置文件 ~/.gemini/settings.json：

{
  "apiKey": "你的APIKey"
}

方案四：检查 Google Cloud 项目冲突

如果你有多个 Google 账号或 Google Cloud 项目，可能出现权限冲突：

# 查看当前认证状态
gemini auth status

# 登出所有账号后重新选择目标账号
gemini auth logout
gemini auth login

确保在浏览器中选择正确的 Google 账号（已开通相应订阅的账号）。