跳转到内容
Gemini CLI 文档

故障排除指南

故障排除指南

Section titled “故障排除指南”

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

  • 认证或登录错误
  • 常见问题解答（FAQ）
  • 调试技巧
  • 与您遇到的问题相似的现有 GitHub Issues 或创建新 Issues

认证或登录错误

Section titled “认证或登录错误”

  • 错误： You must be a named user on your organization's Gemini Code Assist Standard edition subscription to use this service. Please contact your administrator to request an entitlement to Gemini Code Assist Standard edition.

    • 原因： 如果 Gemini CLI 检测到定义了 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID 环境变量，可能会发生此错误。 设置这些变量会强制进行组织订阅检查。 如果您使用的是未与组织订阅关联的个人 Google 帐户，这可能会是一个问题。

    • 解决方案：

      • 个人用户： 取消设置 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_PROJECT_ID 环境变量。检查并从您的 shell 配置文件（例如，.bashrc, .zshrc) 和任何 .env 文件中删除这些变量。 如果这不能解决问题，请尝试使用不同的 Google 帐户。

      • 组织用户： 联系您的 Google Cloud 管理员，将其添加到组织的 Gemini Code Assist 订阅中。

  • 错误: 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_USE_SYSTEM_CA；如果问题仍未解决，设置 NODE_EXTRA_CA_CERTS。
      • 设置 NODE_USE_SYSTEM_CA=1 环境变量，告诉 Node.js 使用操作系统的本地证书存储（通常企业证书已经安装在这里）。
        • 示例：export NODE_USE_SYSTEM_CA=1
      • 将 NODE_EXTRA_CA_CERTS 环境变量设置为您的企业根 CA 证书文件的绝对路径。
        • 示例：export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

常见错误信息及解决方案

Section titled “常见错误信息及解决方案”

  • 错误：启动 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 可能会尝试被您的沙盒配置限制的操作，例如在项目目录或系统临时目录之外写入。
    • 解决方案： 请参考 配置：沙盒 文档获取更多信息，包括如何自定义您的沙盒配置。

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

    • 问题： 如果设置了以 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=true 文件中设置 .env 不会启用 gemini-cli 的调试模式。
  • 原因： 为了防止干扰 gemini-cli 的行为，自动排除了项目 .env 文件中的 DEBUG 和 DEBUG_MODE 变量。
  • 解决方案： 使用 .gemini/.env 文件，或者在您的 settings.json 中配置 advanced.excludedEnvVars 设置以排除更少的变量。

退出码

Section titled “退出码”

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

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

调试技巧

Section titled “调试技巧”
  • CLI 调试：
    • 使用 --debug 标志以获取更详细的输出。
    • 检查 CLI 日志，通常可以在用户特定的配置或缓存目录中找到。

核心调试：

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

工具问题：

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

预检检查：

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

查找类似问题或创建新问题

Section titled “查找类似问题或创建新问题”

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

注意： 标记为“🔒仅维护者”的问题是专为项目维护者保留的。我们将不接受与这些问题相关的拉取请求。