第一章. Gemini CIL 从零开始：安装与认证

第一章. Gemini CIL 从零开始：安装与认证

2025 年初，当我们谈论 AI 编程工具时，桌面上摆着三张牌：Claude Code、Codex CLI 和 Gemini CLI。Claude Code 是全能选手，什么都能干，但每月 20 美元的订阅费让不少独立开发者望而却步。Codex CLI 在后端重构和 Bug 修复上表现出色，但前端支持一直不温不火。

而 Gemini CLI，Google 在 2025 年 6 月悄然发布的这个开源工具，用一个几乎不可能的条件吸引了大量开发者：每天 1000 次免费请求，每分钟 60 次，配合 Gemini 3 Pro 模型对前端代码生成的深度优化，直接把门槛降到了地板价。

这不是说 Gemini CLI 只能写前端。它能做的事情很多：代码生成、审查、文档编写、自动化任务。但如果你主要做前端开发，或者你是独立开发者、学生党，预算有限但需求不少，Gemini CLI 就是那个最合适的选择。100 万 Token 的上下文窗口 意味着你可以把整个 React 项目的代码一次性喂给它，让它理解你的组件结构、状态管理逻辑，然后生成符合项目风格的新代码。

本章将带你完成 Gemini CLI 的安装和认证配置。我们会对比三种认证方式的适用场景，并解决常见的认证问题。学完本章，你将能够在任何环境下顺利启动 Gemini CLI。

1.1. 五分钟快速上手

很多人第一次接触命令行工具时会有点紧张：“我需要配置很多东西吗？” 答案是：不需要。Gemini CLI 的设计理念就是 开箱即用。

安装 Gemini CLI 有两种方式。如果你只是想临时体验一下，不想在系统里留下任何痕迹，直接在终端运行：

1
npx https://github.com/google-gemini/gemini-cli

这条命令会临时下载并运行 Gemini CLI，用完就走，不会在你的系统里安装任何东西。但如果你打算长期使用，还是建议全局安装：

1
npm install -g @google/gemini-cli

安装完成后，我们需要验证一下是否成功。在终端输入：

1
gemini --version

如果看到类似 0.1.7 这样的版本号，就说明安装成功了。首次启动时，CLI 会引导你完成初始配置。

步骤 1：选择主题

运行 gemini 后，第一个界面是主题选择。Gemini CLI 提供了多种终端主题，从 GitHub 风格到高对比度暗色主题都有。这不是什么重要的选择，选一个你看着舒服的就行。我个人比较喜欢 GitHub 主题，因为它的代码高亮比较清晰。

步骤 2：认证配置

接下来是认证环节。这是最关键的一步，因为没有认证，Gemini CLI 就无法调用 Google 的 AI 模型。

1.2. 三种认证方式的深度对比

Gemini CLI 支持三种认证方式：Google 登录、API Key 和 Vertex AI。很多人会问：“我该选哪个？” 这取决于你的使用场景。

适用场景：个人开发者、学生、独立开发者

优势：

  • 每天 1000 次免费请求
  • 每分钟 60 次请求
  • 支持 Gemini 2.5 Pro（100 万 Token 上下文）
  • 浏览器授权，无需管理密钥

操作步骤：运行 gemini 后选择 “Login with Google”，浏览器会自动打开，要求你用 Google 账户授权。授权完成后，凭证会自动缓存在本地，下次启动时不需要重新登录。

计费方式：免费额度用完后，会自动切换到付费模式。但对于大多数个人开发者来说，每天 1000 次请求已经足够了。我自己用了三个月，从来没有超过这个限制。

适用场景：脚本自动化、CI/CD 集成、需要精确控制成本

优势：

  • 适合无头环境（服务器、Docker 容器）
  • 可以在多个项目间共享
  • 计费透明，按实际使用量付费

操作步骤：访问 https://aistudio.google.com/apikey 生成一个 API Key，然后在项目目录创建 .env 文件：

1
GEMINI_API_KEY=你的API密钥

如果想设置永久环境变量，打开 ~/.zshrc（或 ~/.bashrc），添加：

1
export GEMINI_API_KEY="你的API密钥"

保存后运行 source ~/.zshrc 生效。

速率限制：
API Key 方式的速率限制取决于你的付费计划。免费用户每分钟 15 次请求，付费用户可以提升到 60 次甚至更高。

适用场景：企业用户、需要 IAM 权限控制、已有 Google Cloud 项目

优势：

  • 与 Google Cloud IAM 集成
  • 支持 Service Account
  • 可以设置细粒度的权限控制
  • 适合团队协作

操作步骤：设置必需的环境变量：

1
2
3
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_GENAI_USE_VERTEXAI=true

然后选择一种认证方式：

方式 A：使用 gcloud ADC

1
gcloud auth application-default login

方式 B：使用 Service Account 密钥

1
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"

方式 C：使用 Google Cloud API Key

1
export GOOGLE_API_KEY="your-google-api-key"

计费方式：按照 Google Cloud 的标准计费，费用会计入你的 GCP 账单。适合需要统一管理云资源成本的企业。

1.3. 认证故障排查

在实际使用中，我遇到过不少认证相关的问题。这里总结一下最常见的三种错误和解决方案。

如果你在公司网络或使用代理，认证可能会失败。请先检查网络环境。

问题 1：UNAUTHENTICATED 错误

当你看到这个错误时，通常有三种原因：

  1. 凭证过期：Google OAuth Token 有效期是 1 小时。如果你长时间没用，Token 会过期。解决方法：重新运行 gemini，选择 /auth 重新登录。

  2. 环境变量冲突：如果你同时设置了 GEMINI_API_KEY 和 Google 登录，CLI 可能会混淆。解决方法：检查 ~/.gemini/.env 文件，删除不需要的配置。

  3. API Key 无效：如果你用的是 API Key 方式，可能是 Key 本身有问题。解决方法：去 AI Studio 重新生成一个 Key。

问题 2：代理环境下的认证配置

如果你在公司网络，可能需要配置 HTTP 代理。在 ~/.gemini/.env 中添加：

1
2
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080

问题 3：多项目切换时的凭证管理

假设你有两个项目，一个用个人 Google 账号，一个用公司的 Vertex AI。怎么管理？

我的做法是在每个项目目录下创建独立的 .gemini/.env 文件：

1
2
3
4
5
6
7
8
9
10
11
12
# 项目 A：个人项目
cd ~/projects/personal-app
mkdir -p .gemini
echo 'GEMINI_AUTH_TYPE=google' > .gemini/.env

# 项目 B：公司项目
cd ~/projects/company-app
mkdir -p .gemini
cat > .gemini/.env << EOF
GOOGLE_CLOUD_PROJECT=company-project-id
GOOGLE_GENAI_USE_VERTEXAI=true
EOF

这样，Gemini CLI 会根据当前目录自动选择对应的认证方式。

1.4. 实战：配置 CI/CD 环境

很多人问：“我能在 GitHub Actions 里用 Gemini CLI 吗？” 答案是可以的，但需要一些额外配置。

这里我们用 GitHub Actions 作为例子，演示如何在 CI/CD 环境中使用 Gemini CLI。

步骤 1：创建 API Key

首先去 AI Studio 生成一个 API Key。注意，不要用 Google 登录方式，因为 CI 环境没有浏览器。

步骤 2：添加 GitHub Secret

在你的 GitHub 仓库设置中，添加一个 Secret，名字叫 GEMINI_API_KEY，值是你刚才生成的 API Key。

步骤 3：配置 Workflow

创建 .github/workflows/code-review.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Gemini CLI
        run: npm install -g @google/gemini-cli

      - name: Run Code Review
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          git diff origin/main...HEAD > changes.diff
          gemini -p "Review this code for security and performance issues" < changes.diff > review.txt
          cat review.txt >> $GITHUB_STEP_SUMMARY

这个 Workflow 会在每次 Pull Request 时自动运行，用 Gemini CLI 审查代码变更，并把结果输出到 GitHub 的 Summary 页面。

权限最小化原则：

在生产环境中，建议创建一个专门的 Service Account，只授予必要的权限。比如，如果只需要调用 Gemini API，就不要给它访问 Cloud Storage 的权限。

1.5. 本节小结

我们在本节完成了 Gemini CLI 的安装和认证配置。核心要点：

认证方式适用场景免费额度速率限制
Google 登录个人开发1000 次/天60 次/分钟
API Key脚本自动化按计划15-60 次/分钟
Vertex AI企业团队无按配置

速查代码：

1
2
3
4
5
6
7
8
9
10
11
12
# 快速安装
npm install -g @google/gemini-cli

# 验证安装
gemini --version

# 设置 API Key（永久）
echo 'export GEMINI_API_KEY="your-key"' >> ~/.zshrc
source ~/.zshrc

# 启动 CLI
gemini

下一节，我们将学习 Gemini CLI 的基础交互方式，包括如何引用文件、执行命令、管理对话。