常见问题 (FAQ)

本页汇总在使用 Gemini CLI 时经常遇到的问题及解决方案。

常规问题

为什么出现 API error: 429 - Resource exhausted？

该错误表示你的 API 请求超出了限制。Gemini API 通过速率限制防止滥用并保障公平使用。

解决方法：

  • 检查使用量： 在 Google AI Studio 或 Google Cloud 项目控制台查看 API 使用情况。
  • 优化 Prompt： 如果短时间内请求过多，尝试合并请求或在请求之间增加间隔。
  • 申请配额提升： 如长期需要更高配额，可向 Google 申请提升。

为什么运行 npm run start 时出现 ERR_REQUIRE_ESM？

该错误常见于 Node.js 项目中 CommonJS 与 ES Modules 配置不一致。

通常是 package.json 或 tsconfig.json 配置不当。请确认：

  1. package.json 中包含 "type": "module"。
  2. tsconfig.json 的 compilerOptions 中将 "module" 设置为 "NodeNext" 或兼容选项。

若问题仍存在，尝试删除 node_modules 目录和 package-lock.json 文件，然后重新执行 npm install。

为什么统计输出中看不到缓存 Token？

只有在实际使用缓存 Token 时才会显示相关信息。该功能适用于使用 API key 的用户（Gemini API key 或 Google Cloud Vertex AI），不适用于 OAuth 用户（例如 Google 个人或企业账号，如 Gmail、Google Workspace）。原因是 Gemini Code Assist API 不支持缓存内容创建。你仍可通过 Gemini CLI 中的 /stats 命令查看 Token 总用量。

安装与更新

如何将 Gemini CLI 更新到最新版本？

如果通过 npm 全局安装，可使用 npm install -g @google/gemini-cli@latest 更新。若从源码构建，请先拉取仓库最新代码，再执行 npm run build。

平台相关问题

为什么在 Windows 上运行 chmod +x 这类命令会让 CLI 崩溃？

chmod 等命令属于类 Unix 系统（Linux、macOS），Windows 默认不提供。

可采取以下方案：

  • 使用 Windows 等效命令： 例如用 icacls 修改 Windows 上的文件权限。
  • 使用兼容层： 借助 Git Bash 或 Windows Subsystem for Linux (WSL) 提供的类 Unix 环境执行这些命令。

配置

如何配置 GOOGLE_CLOUD_PROJECT？

可以通过环境变量设置 Google Cloud Project ID。

在 Shell 中设置 GOOGLE_CLOUD_PROJECT 环境变量：

export GOOGLE_CLOUD_PROJECT="your-project-id"

若想永久生效，将该行添加到 Shell 启动脚本（如 ~/.bashrc、~/.zshrc）。

如何安全存储我的 API key？

在脚本中暴露 API key 或将其提交到版本库都存在安全风险。

安全存储方式包括：

  • 使用 .env 文件： 在项目的 .gemini 目录下创建 .gemini/.env 文件，并将 key 写入其中。Gemini CLI 会自动加载这些变量。
  • 使用系统秘钥管理： 为最高安全性，可使用操作系统自带的秘钥管理工具（如 macOS Keychain、Windows Credential Manager 或 Linux 上的秘钥管理器），让脚本或环境在运行时读取。

Gemini CLI 的配置文件存放在哪里？

Gemini CLI 将配置保存在两个 settings.json 文件中：

  1. 用户目录：~/.gemini/settings.json
  2. 项目根目录：./.gemini/settings.json

更多信息请参阅 Gemini CLI 配置。

Google AI Pro/Ultra 及订阅相关问题

在哪里可以了解我的 Google AI Pro 或 Google AI Ultra 订阅？

请在订阅设置中的 Manage subscription 查看 Google AI Pro 或 Google AI Ultra 订阅的详情。

如何确认自己是否拥有 Google AI Pro 或 Ultra 的更高配额？

订阅 Google AI Pro 或 Ultra 后，你在 Gemini Code Assist 与 Gemini CLI 中会自动获得更高的配额，这些配额在 Gemini CLI 与 IDE 中的 agent 模式共享。可以在订阅设置确认订阅状态。

如果我订阅了 Google AI Pro 或 Ultra，使用 Gemini Code Assist 或 Gemini CLI 时的隐私政策是什么？

请访问 Gemini Code Assist：服务条款与隐私政策 了解与你的订阅相关的隐私政策和服务条款。

我已经升级到 Google AI Pro 或 Ultra，但仍然提示触达配额上限，这是 Bug 吗？

Google AI Pro 或 Ultra 提供的更高配额适用于 Gemini 2.5（包括 Gemini 2.5 Pro 和 Flash），这些配额在 Gemini CLI 与 Gemini Code Assist IDE 扩展的 agent 模式之间共享。你可以在 配额与限制说明 了解 Gemini CLI、Gemini Code Assist 及 agent 模式的配额详情。

如果我通过购买 Google AI Pro 或 Ultra 获得更高配额，Gemini 会使用我的数据来改进机器学习模型吗？

如果你购买付费套餐，Google 不会使用你的数据来提升 Google 的机器学习模型。注意：若你仍然使用免费版 Gemini Code Assist（Gemini Code Assist for individuals），也可以选择不让数据用于改进 Google 的机器学习模型。详情请查看 Gemini Code Assist for individuals 隐私声明。

还没找到你的问题？

可以搜索 GitHub 上的 Gemini CLI 问答讨论， 或 在 GitHub 发起新的讨论。