故障排除指南

本指南提供了常见问题解决方案和调试技巧，包括以下主题：

• 身份验证或登录错误
• 常见问题解答 (FAQ)
• 调试技巧
• 查找与您类似的问题或创建新问题

身份验证或登录错误

• 错误：Failed to login. Message: Request contains an invalid argument

  • 与 Gmail 账户关联的 Google Workspace 账户或 Google Cloud 账户用户可能无法激活 Google Code Assist 计划的免费套餐。
  • 对于 Google Cloud 账户，您可以通过将 GOOGLE_CLOUD_PROJECT 设置为您的项目 ID 来解决此问题。
  • 或者，您可以从 Google AI Studio 获取 Gemini API 密钥，该密钥也包含一个单独的免费套餐。

• 错误：UNABLE_TO_GET_ISSUER_CERT_LOCALLY 或 unable to get local issuer certificate

  • 原因： 您可能位于一个企业网络中，该网络具有会拦截和检查 SSL/TLS 流量的防火墙。这通常需要 Node.js 信任自定义根 CA 证书。
  • 解决方案： 将 NODE_EXTRA_CA_CERTS 环境变量设置为您的企业根 CA 证书文件的绝对路径。
    • 示例：export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

常见错误消息和解决方案

• 错误：启动 MCP 服务器时出现 EADDRINUSE (地址已在使用中)。

  • 原因： 另一个进程已在使用 MCP 服务器尝试绑定的端口。
  • 解决方案： 停止使用该端口的另一个进程，或配置 MCP 服务器使用不同的端口。

• 错误：命令未找到 (尝试使用 gemini 运行 Gemini CLI 时)。

  • 原因： Gemini CLI 未正确安装，或者未在系统的 PATH 中。
  • 解决方案： 更新取决于您安装 Gemini CLI 的方式：
    • 如果您全局安装了 gemini，请检查您的 npm 全局二进制目录是否在 PATH 中。您可以使用命令 npm install -g @google/gemini-cli@latest 更新 Gemini CLI。
    • 如果您从源代码运行 gemini，请确保使用正确的命令调用它 (例如，node packages/cli/dist/index.js ...)。要更新 Gemini CLI，请拉取存储库的最新更改，然后使用命令 npm run build 重新构建。

• 错误：MODULE_NOT_FOUND 或导入错误。

  • 原因： 依赖项未正确安装，或者项目尚未构建。
  • 解决方案：
    1. 运行 npm install 以确保所有依赖项都存在。
    2. 运行 npm run build 以编译项目。
    3. 通过运行 npm run start 验证构建是否成功完成。

• 错误：“操作不允许”、“权限被拒绝”或类似错误。

  • 原因： 启用沙箱时，Gemini CLI 可能会尝试执行沙箱配置限制的操作，例如写入项目目录或系统临时目录之外。
  • 解决方案： 有关更多信息，包括如何自定义沙箱配置，请参阅 配置：沙箱 文档。

• Gemini CLI 在“CI”环境中未以交互模式运行

  • 问题： 如果设置了以 CI_ 开头的环境变量 (例如 CI_TOKEN)，Gemini CLI 将不会进入交互模式 (不显示提示符)。这是因为底层 UI 框架使用的 is-in-ci 包会检测这些变量并假定为非交互式 CI 环境。
  • 原因： is-in-ci 包会检查 CI、CONTINUOUS_INTEGRATION 或任何带有 CI_ 前缀的环境变量是否存在。当找到任何一个时，它会发出信号表明环境是非交互式的，这会阻止 Gemini CLI 以其交互模式启动。
  • 解决方案： 如果 CLI 功能不需要 CI_ 前缀的变量，您可以在命令中临时取消设置它。例如：env -u CI_TOKEN gemini

• 从项目 .env 文件中 DEBUG 模式不起作用

  • 问题： 在项目的 .env 文件中设置 DEBUG=true 不会为 gemini-cli 启用调试模式。
  • 原因： DEBUG 和 DEBUG_MODE 变量会自动从项目 .env 文件中排除，以防止干扰 gemini-cli 的行为。
  • 解决方案： 改用 .gemini/.env 文件，或者在 settings.json 中配置 advanced.excludedEnvVars 设置以排除较少的变量。

退出代码

Gemini CLI 使用特定的退出代码来指示终止原因。这对于脚本编写和自动化特别有用。

退出代码	错误类型	描述
41	FatalAuthenticationError	在身份验证过程中发生错误。
42	FatalInputError	向 CLI 提供了无效或缺失的输入。(仅限非交互模式)
44	FatalSandboxError	沙箱环境 (例如 Docker、Podman 或 Seatbelt) 出现错误。
52	FatalConfigError	配置文件 (settings.json) 无效或包含错误。
53	FatalTurnLimitedError	已达到会话的最大对话轮数。(仅限非交互模式)

调试技巧

• CLI 调试：

  • 在 CLI 命令中使用 --verbose 标志 (如果可用) 以获得更详细的输出。
  • 检查 CLI 日志，通常位于用户特定的配置或缓存目录中。

• 核心调试：

  • 检查服务器控制台输出中的错误消息或堆栈跟踪。
  • 如果可配置，请增加日志详细程度。
  • 如果需要单步调试服务器端代码，请使用 Node.js 调试工具 (例如 node --inspect)。

• 工具问题：

  • 如果特定工具失败，请尝试通过运行该工具执行的最简单命令或操作版本来隔离问题。
  • 对于 run_shell_command，请先检查命令是否可以直接在您的 shell 中运行。
  • 对于 文件系统工具，请验证路径是否正确并检查权限。

• 预检检查：

  • 在提交代码之前，请始终运行 npm run preflight。这可以捕获许多与格式、linting 和类型错误相关的常见问题。

查找与您类似的问题或创建新问题

如果您遇到本 故障排除指南 中未涵盖的问题，请考虑搜索 Gemini CLI GitHub 上的问题跟踪器。如果您找不到与您遇到的问题类似的问题，请考虑创建一个新的 GitHub Issue 并附上详细描述。也欢迎提交拉取请求！