跳转至

故障排除指南

本指南提供常见问题的解决方案和调试技巧。

认证问题

  • 错误：登录失败。消息：请求包含无效参数

  • 使用 Google Workspace 账户的用户，或 Google Cloud 账户与 Gmail 账户关联的用户可能无法激活 Google Code Assist 的免费套餐。

  • 对于 Google Cloud 账户，可以通过设置 GOOGLE_CLOUD_PROJECT 为您的项目 ID 来解决此问题。
  • 您也可以从 AI Studio 获取 API 密钥，该平台也提供独立的免费套餐。

常见问题解答 (FAQs)

  • 问：如何将 Gemini CLI 更新到最新版本？

  • 答：如果是通过 npm 全局安装的，使用命令 npm install -g @google/gemini-cli@latest 更新 Gemini CLI。如果是通过源代码运行的，从代码库拉取最新更改并使用 npm run build 重新构建。

  • 问：Gemini CLI 的配置文件存储在何处？

  • 答：CLI 配置存储在两个 settings.json 文件中：一个在您的用户主目录下，另一个在项目根目录下。在这两个位置中，settings.json 都位于 .gemini/ 文件夹内。更多详情请参阅 CLI 配置。

  • 问：为什么在我的统计输出中看不到缓存的 token 计数？

  • 答：只有当使用缓存的 token 时才会显示缓存 token 信息。此功能目前仅适用于 API 密钥用户（Gemini API 密钥或 Vertex AI），而不适用于 OAuth 用户（Google 个人/企业账户），因为 Code Assist API 不支持创建缓存内容。您仍然可以使用 /stats 命令查看总 token 使用量。

常见错误信息及解决方案

  • 错误：EADDRINUSE (地址已被占用) 当启动 MCP 服务器时

  • 原因： 其他进程已占用了 MCP 服务器尝试绑定的端口

  • 解决方案： 停止使用该端口的其他进程，或配置 MCP 服务器使用其他端口

  • 错误：命令未找到 (当尝试运行 Gemini CLI 时)

  • 原因： Gemini CLI 未正确安装或不在系统 PATH 中

  • 解决方案：

    1. 确保 Gemini CLI 安装成功
    2. 如果是全局安装，检查 npm 全局二进制目录是否在 PATH 中
    3. 如果从源码运行，确保使用正确的命令调用 (例如 node packages/cli/dist/index.js ...)

  • 错误：MODULE_NOT_FOUND 或导入错误

  • 原因： 依赖未正确安装，或项目未构建

  • 解决方案：

    1. 运行 npm install 确保所有依赖存在
    2. 运行 npm run build 编译项目

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

  • 原因： 如果启用了沙盒功能，可能是应用程序尝试执行了沙盒限制的操作，例如在项目目录或系统临时目录之外进行写入

  • 解决方案： 查看沙盒配置获取更多信息，包括如何自定义沙盒配置

调试技巧

  • CLI调试:

  • 使用 --verbose 标志（如果可用）运行 CLI 命令以获取更详细的输出

  • 检查 CLI 日志，通常位于用户特定的配置或缓存目录中

  • 核心调试:

  • 检查服务器控制台输出中的错误信息或堆栈跟踪

  • 如果可配置，请增加日志详细程度

  • 如果需要单步调试服务器端代码，可使用 Node.js 调试工具（如 node --inspect）

  • 工具问题:

  • 如果特定工具失败，尝试通过运行该工具执行的最简化版命令或操作来隔离问题

  • 对于 run_shell_command，请先检查该命令是否能在你的 shell 中直接运行

  • 对于文件系统工具，请仔细检查路径和权限

  • 预检检查:

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

如果遇到本文档未涵盖的问题，建议在项目的 GitHub issue 跟踪器中搜索或提交包含详细信息的新 issue。