Gemini-cli安装避坑指南

Gemini-CLI 安装与使用教程

本文由Gemini-CLI生成，分享在鉴权过程中可能遇到的常见问题。

1. 安装

您可以使用 npm (或 yarn, pnpm) 全局安装 Gemini-CLI：

npm install -g @google/gemini-cli

安装完成后，您可以通过以下命令验证安装是否成功：

gemini --version

2. 基础使用

安装并完成鉴权后，您可以开始使用 Gemini-CLI。一个简单的测试是：

gemini hi

3. 鉴权 (gemini auth)

在使用 Gemini-CLI 的大部分功能之前，您需要进行鉴权，将 CLI 工具与您的 Google 账号关联。

执行以下命令启动鉴权流程：

gemini auth

该命令会生成一个 URL，请在浏览器中打开它，登录您的 Google 账号，并授权 Gemini-CLI 访问。成功后，将授权码复制回终端即可完成鉴权。

---

4. 鉴权常见问题与解决方案

在鉴权的过程中，您可能会遇到以下问题。

4.1 缺少 GOOGLE_CLOUD_PROJECT 环境变量

问题描述:

在登录成功后，终端可能会提示错误，指出 GOOGLE_CLOUD_PROJECT 环境变量未设置。这是因为 Gemini-CLI 需要关联一个 Google Cloud 项目来进行配额和计费管理。

解决方案:

1. 获取您的 Project ID:

   • 访问 Google Cloud Console。
   • 在顶部导航栏的项目选择器中，选择您要用于 Gemini-CLI 的项目。
   • 在项目仪表盘 (Dashboard) 的 "Project info" 卡片中，找到并复制您的 Project ID。

2. 设置环境变量:

   • 在您的终端中，执行以下命令来设置环境变量。请将 your-project-id 替换为您真实的 Project ID。

   export GOOGLE_CLOUD_PROJECT=your-project-id

   • 提示: 为了让这个配置永久生效，建议将此命令添加到您的 shell 配置文件中（如 ~/.zshrc, ~/.bashrc 或 ~/.profile），然后执行 source ~/.zshrc (或相应文件) 使其立即生效。

4.2 鉴权超时 (Auth Timeout)

问题描述:

执行 gemini auth 后，终端长时间没有响应，或者在尝试连接到 Google 认证服务时最终显示超时错误。这通常是由于本地网络环境无法直接或稳定地访问 Google 的服务器。

解决方案:

您需要为终端设置 HTTP/HTTPS 代理来解决此问题。

1. 获取您的代理地址和端口:

   • 确保您有一个可以正常工作的本地或远程代理服务。
   • 获取其 IP 地址（或域名）和端口号。常见的本地代理端口有 7890, 1080, 8889 等。

2. 方案一：设置终端环境变量

   • 在终端中执行以下命令。请将 your-proxy-address 和 port 替换为您的实际代理信息。

   export http_proxy=http://your-proxy-address:port
   export https_proxy=http://your-proxy-address:port

   • 示例 (如果您的代理在本地，端口为 7890):

     export http_proxy=http://127.0.0.1:7890
     export https_proxy=http://127.0.0.1:7890

3. 方案二：修改 CLI 源码

   • 如果您通过 nvm 管理 Node.js 版本，可以找到 Gemini-CLI 的安装目录并直接修改其启动文件来硬编码代理。

   • 示例路径 (您的版本和路径可能不同): ~/.nvm/versions/node/v20.18.1/lib/node_modules/@google/gemini-cli/dist/index.js

   • 修改内容: 在文件顶部添加以下代码来设置代理。

   import './src/gemini.js';
   import { main } from './src/gemini.js';
   
   // --- Start of proxy configuration ---
   process.env.HTTPS_PROXY = 'http://127.0.0.1:7890';
   process.env.HTTP_PROXY = 'http://127.0.0.1:7890';
   process.env.ALL_PROXY = 'socks5://127.0.0.1:7890';
   // --- End of proxy configuration ---
   main().catch((error) => {
       console.error('An unexpected critical error occurred:');
       if (error instanceof Error) {
           console.error(error.stack);
       }
       else {
           console.error(String(error));
       }
       process.exit(1);
   });

4. 重新鉴权:

   • 设置好代理后，再次运行 gemini 命令，此时它应该能通过代理成功连接到 Google 服务。

   • 提示: 与 GOOGLE_CLOUD_PROJECT 类似，您也可以将 http_proxy 和 https_proxy 的 export 命令添加到 shell 配置文件中，以便在需要时使用。在不需要代理时，可以使用 unset http_proxy https_proxy 命令来取消设置。

5. 总结

完成以上步骤后，您的 Gemini-CLI 应该已经配置完毕，可以正常使用了。如果在操作中遇到其他问题，建议查阅官方文档或使用 --help 参数查看命令帮助。