主题
常见问题 (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 重新构建。
平台特定问题
为什么在 Windows 上运行 chmod +x 等命令时 CLI 崩溃？
像 chmod 这样的命令是 Unix 类操作系统（Linux、macOS）特有的。它们在 Windows 上默认不可用。
要解决此问题，你可以：
- 使用 Windows 等效命令： 代替
chmod，你可以使用icacls在 Windows 上修改文件权限。 - 使用兼容层： Git Bash 或 Windows Subsystem for Linux (WSL) 等工具在 Windows 上提供类 Unix 环境，这些命令可以在其中工作。
配置
如何配置我的 GOOGLE_CLOUD_PROJECT？
你可以使用环境变量配置你的 Google Cloud 项目 ID。
在你的 shell 中设置 GOOGLE_CLOUD_PROJECT 环境变量：
bash
export GOOGLE_CLOUD_PROJECT="your-project-id"要使此设置永久生效，将此行添加到你的 shell 启动文件（例如 ~/.bashrc、~/.zshrc）。
安全存储 API 密钥的最佳方式是什么？
在脚本中暴露 API 密钥或将其检入源代码控制是安全风险。
要安全存储你的 API 密钥，你可以：
- 使用
.env文件： 在项目的.gemini目录（.gemini/.env）中创建.env文件并在其中存储密钥。Gemini CLI 将自动加载这些变量。 - 使用系统的密钥环： 为了最安全的存储，使用操作系统的密钥管理工具（如 macOS 钥匙串、Windows 凭据管理器或 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 Pro 和 Flash 的 Gemini 2.5。它们是 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），你也可以选择退出使用你的数据来改进 Google 的机器学习模型。有关更多信息，请参阅 个人版 Gemini Code Assist 隐私声明。