常见问题解答 (FAQ)
本页面提供了在使用 Gemini CLI 时遇到的常见问题解答和解决方案。
一般问题
为什么我收到 API error: 429 - Resource exhausted 错误？
此错误表明您已超出 API 请求限制。Gemini API 设有速率限制，以防止滥用并确保公平使用。
要解决此问题，您可以：
- 检查您的使用情况： 在 Google AI Studio 或您的 Google Cloud 项目信息中心查看您的 API 使用情况。
- 优化您的提示： 如果您在短时间内发出大量请求，请尝试批量处理提示或在请求之间引入延迟。
- 请求增加配额： 如果您持续需要更高的限制，可以向 Google 申请增加配额。
运行 npm run start 时为什么会收到 ERR_REQUIRE_ESM 错误？
此错误通常在 Node.js 项目中出现，表示 CommonJS 和 ES Modules 之间存在不匹配。
这通常是由于您的 package.json 或 tsconfig.json 配置不当所致。请确保：
- 您的
package.json包含"type": "module"。 - 您的
tsconfig.json在compilerOptions中包含"module": "NodeNext"或兼容的设置。
如果问题仍然存在，请尝试删除您的 node_modules 目录和 package-lock.json 文件，然后再次运行 npm install。
为什么我的统计信息输出中看不到缓存的 token 计数？
仅当正在使用缓存的 token 时，才会显示缓存的 token 信息。此功能适用于 API 密钥用户（Gemini API 密钥或 Google Cloud Vertex AI），但不适用于 OAuth 用户（例如 Google 个人/企业帐户，如 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 重新构建。
特定于平台的 issues
为什么我在 Windows 上运行 chmod +x 等命令时 CLI 会崩溃？
chmod 等命令特定于类 Unix 操作系统（Linux、macOS）。它们在 Windows 上默认不可用。
要解决此问题，您可以：
- 使用 Windows 等效命令： 在 Windows 上，可以使用
icacls修改文件权限，而不是chmod。 - 使用兼容层： Git Bash 或 Windows Subsystem for Linux (WSL) 等工具可在 Windows 上提供类 Unix 环境，使这些命令能够正常工作。
配置
如何配置我的 GOOGLE_CLOUD_PROJECT？
您可以使用环境变量配置您的 Google Cloud 项目 ID。
在您的 shell 中设置 GOOGLE_CLOUD_PROJECT 环境变量：
export GOOGLE_CLOUD_PROJECT="your-project-id"要使此设置永久生效，请将此行添加到您的 shell 启动文件（例如 ~/.bashrc、~/.zshrc）中。
存储 API 密钥的安全最佳方法是什么？
在脚本中暴露 API 密钥或将其检入源代码控制存在安全风险。
要安全地存储您的 API 密钥，您可以：
- 使用
.env文件： 在项目的.gemini目录 (.gemini/.env) 中创建一个.env文件，并将您的密钥存储在那里。Gemini CLI 将自动加载这些变量。 - 使用系统的密钥环： 为了最安全地存储，请使用操作系统的密钥管理工具（如 macOS Keychain、Windows Credential Manager 或 Linux 上的密钥管理器）。然后，您可以在运行时让您的脚本或环境从安全存储中加载密钥。
Gemini CLI 的配置文件和设置文件存储在哪里？
Gemini CLI 的配置存储在两个 settings.json 文件中：
- 在您的主目录中：
~/.gemini/settings.json。 - 在您的项目根目录中：
./.gemini/settings.json。
有关更多详细信息，请参阅 Gemini CLI 配置。
Google AI Pro/Ultra 和订阅常见问题解答
在哪里可以了解更多关于我的 Google AI Pro 或 Google AI Ultra 订阅的信息？
要了解更多关于您的 Google AI Pro 或 Google AI Ultra 订阅的信息，请访问您的订阅设置中的管理订阅。
我如何知道我是否拥有 Google AI Pro 或 Ultra 的更高限制？
如果您订阅了 Google AI Pro 或 Ultra，您将自动获得 Gemini Code Assist 和 Gemini CLI 的更高限制。这些限制在 Gemini CLI 和 IDE 中的代理模式之间共享。您可以通过在您的订阅设置中检查您是否仍订阅 Google AI Pro 或 Ultra 来确认您是否拥有更高的限制。
如果我订阅了 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 扩展中的代理模式之间的共享配额。您可以在配额和限制中了解有关 Gemini CLI、Gemini Code Assist 和 Gemini Code Assist 中代理模式的配额限制的更多信息。
如果我通过购买 Google AI Pro 或 Ultra 订阅来升级 Gemini CLI 和 Gemini Code Assist 的更高限制，Gemini 是否会开始使用我的数据来改进其机器学习模型？
如果您购买了付费套餐，Google 不会使用您的数据来改进 Google 的机器学习模型。注意：如果您选择继续使用 Gemini Code Assist 的免费版本（Gemini Code Assist for individuals），您也可以选择不使用您的数据来改进 Google 的机器学习模型。有关更多信息，请参阅Gemini Code Assist for individuals 隐私声明。