Gemini-cli安装避坑指南

Gemini-CLI 安装与使用教程

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

1. 安装

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

bash 复制代码
npm install -g @google/gemini-cli

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

bash 复制代码
gemini --version

2. 基础使用

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

bash 复制代码
gemini hi

3. 鉴权 (gemini auth)

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

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

bash 复制代码
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。
    bash 复制代码
    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-addressport 替换为您的实际代理信息。
    bash 复制代码
    export http_proxy=http://your-proxy-address:port
    export https_proxy=http://your-proxy-address:port
    • 示例 (如果您的代理在本地,端口为 7890):

      bash 复制代码
      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

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

    javascript 复制代码
    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_proxyhttps_proxyexport 命令添加到 shell 配置文件中,以便在需要时使用。在不需要代理时,可以使用 unset http_proxy https_proxy 命令来取消设置。

5. 总结

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

相关推荐
天若有情6735 小时前
【技术新闻】OpenAI发布GPT-5,AI编程助手迎来革命性突破
gpt·ai编程·业界资讯·新闻资讯
PetterHillWater6 小时前
AI应用与教育行业
aigc
ruokkk8 小时前
claude code搭配Qwen3-Coder干活不累。
ai编程
小小小小小鹿9 小时前
Ai入门-搭建一个专属的ai学习助手
llm·ai编程
showyoui9 小时前
LangChain vs LangGraph:从困惑到清晰的认知之路(扫盲篇)
langchain·ai编程
心在飞扬9 小时前
AI 是搭子不是替代者:我用大模型 + Cursor 编程的一年经验总结
ai编程
redreamSo13 小时前
AI Daily | AI日报:Altman:GPT - 5将引发就业与欺诈变革; OpenAI 新模型多场竞赛‘翻车’,谷歌躺赢!; 黄仁勋:报废50亿显卡,员工薪酬全加薪
程序员·aigc·资讯
猫头虎14 小时前
[精选] 2025最新生成 SSH 密钥和 SSL 证书的标准流程(Linux/macOS/Windows系统服务器通用方案)
linux·服务器·开发语言·macos·ssh·ssl·ai编程
数据智能老司机14 小时前
构建由 LLM 驱动的 Neo4j 应用程序——揭开 RAG 的神秘面纱
langchain·llm·aigc
数据智能老司机14 小时前
构建由 LLM 驱动的 Neo4j 应用程序——构建智能应用的知识图谱基础理解
langchain·llm·aigc