Appearance
本页汇总 Gemini CLI 用户最常遇到的问题和解决方案：从 Google 账号认证错误（组织订阅检查、地区限制）、API 429 配额超限、企业网络 SSL 证书问题，到 Windows 平台兼容性、npm 构建错误、CI 环境下非交互模式等。每个问题都有明确的原因分析和可操作的修复步骤。
故障排查与常见问题
遇到问题？本页按场景分类列出了最常见的错误和解决方案。
认证与登录错误
错误：组织订阅检查失败
You must be a named user on your organization's Gemini Code Assist Standard edition subscription...原因：检测到 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID 环境变量，触发组织订阅检查。
解决方案：
- 个人用户：取消设置这两个环境变量，并从
.bashrc、.zshrc、.env中删除它们 - 企业用户：联系 Google Cloud 管理员，确认你已被添加到组织的 Gemini Code Assist 订阅中
错误：当前位置不可用
Failed to sign in. Message: Your current account is not eligible... because it is not currently available in your location.原因：Gemini CLI 尚未在你所在地区开放。
解决方案：查阅 Gemini Code Assist 支持地区列表。
错误：无效参数
Failed to sign in. Message: Request contains an invalid argument原因：Google Workspace 账号或关联 Gmail 的 Google Cloud 账号无法激活免费层。
解决方案：
- 设置
GOOGLE_CLOUD_PROJECT为你的 Google Cloud 项目 ID - 或从 Google AI Studio 获取 API Key（有独立免费配额）
错误：SSL 证书问题（企业网络）
UNABLE_TO_GET_ISSUER_CERT_LOCALLY
unable to get local issuer certificate原因：企业网络的防火墙拦截并检查 SSL/TLS 流量，需要信任公司自签根证书。
解决方案：
bash
# 方案 1：使用系统证书存储
export NODE_USE_SYSTEM_CA=1
# Windows PowerShell
$env:NODE_USE_SYSTEM_CA=1
# 方案 2：手动指定证书文件
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt
# Windows PowerShell
$env:NODE_EXTRA_CA_CERTS="C:\path\to\corporate-ca.crt"常见错误信息
错误：429 - 配额超限
API error: 429 - Resource exhausted原因：超过了 API 请求频率限制。
解决方案：
- 在 Google AI Studio 或 Google Cloud 控制台检查用量
- 减少短时间内的请求频率，或在请求之间加入延迟
- 如需更高配额，申请配额提升
Google AI Pro/Ultra 订阅用户有更高的共享配额（与 Gemini Code Assist IDE 扩展共享）。
错误：MCP 服务器端口被占用
EADDRINUSE: Address already in use原因：另一个进程占用了 MCP 服务器要绑定的端口。
解决方案：停止占用该端口的进程，或在 MCP 配置中改用其他端口。
错误：命令未找到（gemini: command not found）
原因：Gemini CLI 未正确安装或不在系统 PATH 中。
解决方案：
bash
# 检查 npm 全局安装路径是否在 PATH 中
npm config get prefix
# 重新安装到最新版本
npm install -g @google/gemini-cli@latest错误：MODULE_NOT_FOUND 或导入错误
原因：依赖未安装或项目未构建。
解决方案：
bash
npm install # 安装依赖
npm run build # 重新构建
npm run start # 验证错误：ERR_REQUIRE_ESM
原因：CommonJS 和 ES Modules 配置不匹配。
解决方案：确认 package.json 有 "type": "module"，tsconfig.json 有 "module": "NodeNext"。删除 node_modules 和 package-lock.json 后重新 npm install。
平台特定问题
Windows：chmod +x 命令失败
原因：chmod 是 Unix 命令，Windows 不支持。
解决方案：
- 用
icacls命令修改文件权限（Windows 原生） - 或安装 Git Bash / WSL 获得 Unix 环境
CI/CD 环境：CLI 不进入交互模式
原因：环境变量中存在 CI_ 前缀的变量（如 CI_TOKEN），is-in-ci 包检测到后认为是 CI 环境，禁用交互模式。
解决方案：临时取消设置该变量：
bash
env -u CI_TOKEN gemini配置问题
API Key 安全存储
不要把 API Key 写入脚本或提交到代码仓库。推荐做法：
- 存入
.gemini/.env文件（Gemini CLI 自动加载） - 或使用系统密钥管理器（macOS Keychain、Windows Credential Manager）
GOOGLE_CLOUD_PROJECT 配置
bash
# macOS/Linux（永久生效：加入 .bashrc/.zshrc）
export GOOGLE_CLOUD_PROJECT="your-project-id"
# Windows PowerShell
$env:GOOGLE_CLOUD_PROJECT="your-project-id"配置文件位置
Gemini CLI 的配置存在两个位置：
~/.gemini/settings.json（全局）./.gemini/settings.json（当前项目）
完整字段说明参见 settings.json 参考。
订阅相关问题
配额共享问题
Google AI Pro/Ultra 订阅的配额是 Gemini CLI 和 IDE 插件的 共享配额，使用 IDE 插件的 Agent 模式也会消耗这个配额。
数据隐私
付费计划（Pro/Ultra）不使用你的数据训练模型。免费版用户可以在设置中选择退出数据使用。
没找到你的问题？
在 GitHub Discussions Q&A 中搜索，或查阅我们的 已知问题索引。