故障排查指南

本指南汇总常见问题与调试技巧，涵盖以下内容：

  • 身份验证或登录错误
  • 常见问题解答（FAQ）
  • 调试技巧
  • 参考现有 GitHub Issue 或创建新 Issue

身份验证或登录错误

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

    • 使用 Google Workspace 账号或与 Gmail 关联的 Google Cloud 账号时，可能无法激活 Google Code Assist 的免费层。
    • 若使用 Google Cloud 账号，可通过设置 GOOGLE_CLOUD_PROJECT 为项目 ID 来规避。
    • 也可以从 Google AI Studio 获取 Gemini API key，该渠道同样提供独立的免费层。

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

    • 原因： 你可能处于会拦截并检查 SSL/TLS 流量的企业网络，通常需要 Node.js 信任企业自签根证书。
    • 解决方案： 将 NODE_EXTRA_CA_CERTS 环境变量设置为企业根证书的绝对路径。
      • 示例：export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

常见错误信息与解决方案

  • 错误：启动 MCP server 时出现 EADDRINUSE（端口已占用）。

    • 原因： 其他进程已占用该端口。
    • 解决方案： 停止占用端口的进程，或为 MCP server 配置其他端口。

  • 错误：运行 gemini 时提示命令不存在。

    • 原因： Gemini CLI 未正确安装，或可执行文件不在系统 PATH 中。
    • 解决方案： 根据安装方式不同采取以下措施：
      • 若全局安装了 gemini，确认 npm 全局可执行目录已加入 PATH，并可执行 npm install -g @google/gemini-cli@latest 更新。
      • 若从源码运行 gemini，请使用正确命令（例如 node packages/cli/dist/index.js ...）。更新时先拉取仓库最新代码，再运行 npm run build。

  • 错误：MODULE_NOT_FOUND 或 Import 相关错误。

    • 原因： 依赖安装不完整，或尚未构建项目。
    • 解决方案：
      1. 执行 npm install 安装全部依赖。
      2. 执行 npm run build 编译项目。
      3. 通过 npm run start 确认构建成功。

  • 错误：“Operation not permitted”、“Permission denied”等。

    • 原因： 启用了 Sandboxing 时，Gemini CLI 可能尝试执行沙箱配置禁止的操作，例如写入项目目录外或系统临时目录。
    • 解决方案： 参阅 Sandboxing 配置，了解如何自定义沙箱规则。

  • 问题：在含有 CI 变量的环境中，Gemini CLI 未进入交互模式。

    • 现象： 若环境变量以 CI_ 开头（如 CI_TOKEN），CLI 不会显示交互式提示。
    • 原因： UI 框架依赖的 is-in-ci 会检测 CI、CONTINUOUS_INTEGRATION 或 CI_ 前缀变量，并判定环境为 CI，从而关闭交互模式。
    • 解决方案： 若这些变量对 CLI 运行非必需，可在执行命令时临时取消，例如 env -u CI_TOKEN gemini。

  • 问题：项目 .env 中设置 DEBUG=true 无法启用调试模式。

    • 原因： 为避免影响 gemini-cli 行为，项目级 .env 会自动排除 DEBUG 与 DEBUG_MODE。
    • 解决方案： 请使用 .gemini/.env 文件，或在 settings.json 中调整 advanced.excludedEnvVars。

退出码

Gemini CLI 使用特定退出码标识终止原因，便于脚本或自动化场景处理。

Exit CodeError TypeDescription
41FatalAuthenticationError身份验证过程中发生错误。
42FatalInputError提供给 CLI 的输入无效或缺失（仅限非交互模式）。
44FatalSandboxErrorSandboxing 环境（如 Docker、Podman、Seatbelt）出现错误。
52FatalConfigError配置文件（settings.json）无效或存在错误。
53FatalTurnLimitedError会话达到最大对话轮数（仅限非交互模式）。

调试技巧

  • CLI 调试：

    • 在可用的命令中添加 --verbose 获取更详细输出。
    • 查看 CLI 日志，通常位于用户配置或缓存目录。

  • Core 调试：

    • 检查服务器控制台输出的错误或堆栈信息。
    • 若可配置，提升日志详细程度。
    • 如需单步调试，可使用 Node.js 工具（例如 node --inspect）。

  • 工具相关问题：

    • 若特定工具异常，尝试运行该工具执行的最简命令以定位问题。
    • 对于 run_shell_command，先在 Shell 中直接验证命令是否可用。
    • 对于文件系统类工具，确认路径正确且拥有足够权限。

  • 预检：

    • 在提交代码前运行 npm run preflight，预防格式、Lint、类型等常见问题。

参考现有 Issue 或创建新 Issue

如遇本指南未覆盖的问题，可先在 Gemini CLI 的 GitHub Issue 列表 中搜索。 若找不到相似问题，欢迎提交包含详细描述的新 Issue，也欢迎直接贡献 Pull Request！