Google Gemini CLI 完整使用指南

最近用 Codex 写公司的 ERP 前端页面还是没啥大问题，结合 DESIGN.md 形成统一设计风格之后还是蛮好的。但在自己的项目上写前端页面太降智了，审美太无语了。听大家说 Gemini 写前端页面会好很多，还有 Google Stitch 可以直接设计原型，试了试确实比 Codex 要有想法，审美也好很多。

Gemini CLI 使用示例

1. 简介

Gemini CLI 是 Google 发布的开源 AI Agent，将 Gemini 模型能力直接带入终端。它不是一个简单的聊天工具，而是一个具备 ReAct（推理-行动）循环的智能代理，能够：

读取、分析、修改本地文件和代码库
执行 Shell 命令（带权限控制）
调用 Google Search 进行联网搜索
抓取网页内容
通过 MCP 协议连接外部工具
理解图片、PDF、音频、视频等多模态输入

核心优势：

🆓 慷慨的免费额度：个人 Google 账号每天 1000 次请求、每分钟 60 次（OAuth 登录）
🧠 Gemini 3 模型：访问最新 Gemini 3 系列，支持 100 万 Token 上下文窗口
🔧 内置工具：Google Search、文件操作、Shell 命令、网页抓取
🔌 可扩展：MCP 协议支持自定义工具集成
💻 终端原生：专为命令行开发者设计
☁️ Cloud Shell 预装：Google Cloud Shell 中无需额外安装

2. 环境配置与安装

2.1 系统要求

Node.js：18.0 及以上版本（推荐 20+）
操作系统：macOS、Linux、Windows（含 WSL）
网络：需要能访问 Google 服务

验证 Node.js 版本：

node --version  # 应输出 v18.x.x 或更高

2.2 安装方式

方式一：npm 全局安装（推荐）

npm install -g @google/gemini-cli

方式二：无需安装，直接使用 npx

npx @google/gemini-cli

方式三：Conda 环境（数据科学场景）

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

方式四：安装预览版（最新功能，可能不稳定）

npm install -g @google/gemini-cli@preview

方式五：每日构建版（最前沿，存在未验证问题）

npm install -g @google/gemini-cli@nightly

2.3 升级

npm update -g @google/gemini-cli

2.4 卸载

npm uninstall -g @google/gemini-cli

# 同时清除配置（可选）
rm -rf ~/.gemini

2.5 验证安装

gemini --version

2.6 配置目录结构

Gemini CLI 的文件分布在以下位置：

~/.gemini/                         # 用户全局目录
├── settings.json                  # 用户级配置
├── GEMINI.md                      # 全局上下文文件
├── commands/                      # 用户自定义斜杠命令
│   └── my-command.toml
├── keybindings.json               # 自定义键位绑定
└── agents/                        # 本地 Agent 定义

<project>/
├── .gemini/                       # 项目级配置
│   ├── settings.json              # 项目设置（覆盖用户设置）
│   ├── commands/                  # 项目专属命令
│   │   └── review.toml
│   └── sandbox-macos-custom.sb   # 自定义沙箱配置
├── GEMINI.md                      # 项目上下文文件
└── .geminiignore                  # 忽略文件（类似 .gitignore）

# 系统级（企业管理员使用）
/etc/gemini-cli/settings.json      # Linux 系统级强制配置
C:\ProgramData\gemini-cli\settings.json  # Windows 系统级

3. 认证方式

3.1 方式对比

认证方式	适用人群	每日限额	是否付费
Google 账号 OAuth（个人）	个人开发者	1000 次/天，60次/分钟	免费
Gemini API Key（免费层）	个人/测试	100 次/天（Gemini 2.5 Pro）	免费
Gemini API Key（付费层）	生产/团队	按 Token 计费	付费
Vertex AI（ADC）	企业/GCP 用户	根据 GCP 项目配额	付费
Google Cloud API Key	GCP 项目	根据项目配额	付费
Gemini Code Assist 许可证	企业团队	较高配额	企业付费

3.2 推荐：Google 账号 OAuth（最简单）

首次运行时，CLI 会自动引导认证：

gemini

# 提示选择认证方式
# 选择 "1. Sign in with Google"
# 浏览器弹出 → 选择 Google 账号 → 点击登录

3.3 API Key 认证

# 从 Google AI Studio 获取 Key：https://aistudio.google.com/apikey
export GEMINI_API_KEY="your-api-key-here"
gemini

3.4 Vertex AI 认证（企业/GCP）

# 配置应用默认凭证（ADC）
gcloud auth application-default login

# 设置项目和区域
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_GENAI_USE_VERTEXAI=true

gemini

3.5 Headless（无头）环境认证

在 CI/CD 或服务器中，必须通过环境变量认证：

# 方式 A：Gemini API Key
export GEMINI_API_KEY="your-key"
gemini -p "执行任务"

# 方式 B：Vertex AI + ADC
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export GOOGLE_CLOUD_PROJECT="your-project"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini -p "执行任务"

⚠️ 重要安全警告：如果你设置了 GOOGLE_API_KEY、GEMINI_API_KEY 或 GOOGLE_GENAI_USE_VERTEXAI 环境变量，即使你选择 Google 账号登录，CLI 也会优先使用这些环境变量并走付费 API 通道。如果只想用免费 OAuth，确保这些环境变量没有被设置。

4. 常见环境变量

4.1 认证相关

变量名	说明
`GEMINI_API_KEY`	Gemini API Key（直接访问 Google AI 服务）
`GOOGLE_API_KEY`	Google Cloud API Key（配合 Vertex AI）
`GOOGLE_GENAI_USE_VERTEXAI`	设为 `true` 时使用 Vertex AI 后端
`GOOGLE_APPLICATION_CREDENTIALS`	ADC 服务账号 JSON 文件路径
`GOOGLE_CLOUD_PROJECT`	GCP 项目 ID
`GOOGLE_CLOUD_LOCATION`	GCP 区域（如 `us-central1`）

4.2 配置路径相关

变量名	说明	默认值
`GEMINI_CLI_SYSTEM_DEFAULTS_PATH`	系统默认配置路径	`/etc/gemini-cli/system-defaults.json`
`GEMINI_CONFIG_DIR`	自定义配置目录	`~/.gemini`

5. 基本使用

5.1 交互模式

直接在项目目录下运行：

cd your-project
gemini

进入交互模式后，可以：

输入自然语言问题或指令
使用斜杠命令（/help 查看所有命令）
使用 Ctrl+C 中断当前操作

5.2 非交互模式（单命令）

# 直接执行单个指令
gemini -p "解释这个项目的结构"

# 从文件读取输入
gemini -f instructions.txt

# 管道输入
echo "总结当前目录" | gemini

5.3 沙盒模式

在 macOS 上，Gemini CLI 默认运行在沙盒中，限制对文件系统的访问：

# 使用自定义沙盒配置
gemini --sandbox-config .gemini/sandbox-macos-custom.sb

6. 上下文文件 (GEMINI.md)

GEMINI.md 是 Gemini CLI 的核心功能之一，用于为 AI 提供项目上下文。

6.1 作用

定义项目结构和技术栈
设置编码规范和约定
提供开发工作流说明
包含重要的业务逻辑说明

6.2 示例 GEMINI.md

# 项目上下文

## 技术栈
- Node.js 20+
- TypeScript 5.x
- React 18 + Next.js 14
- Tailwind CSS

## 代码规范
- 使用 ESLint + Prettier
- 组件使用函数式写法
- 文件名使用 kebab-case

## 重要说明
- API 基础路径：/api/v1
- 认证使用 JWT
- 数据库使用 PostgreSQL

6.3 优先级

上下文文件的优先级（从高到低）：

项目级 .gemini/GEMINI.md
项目根目录 GEMINI.md
用户级 ~/.gemini/GEMINI.md

7. MCP 协议集成

Gemini CLI 支持通过 MCP（Model Context Protocol）连接外部工具。

7.1 配置 MCP Server

在 settings.json 中添加：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

7.2 常用 MCP Server

@modelcontextprotocol/server-filesystem：受限文件系统访问
@modelcontextprotocol/server-github：GitHub API 集成
@modelcontextprotocol/server-postgres：PostgreSQL 数据库操作
@modelcontextprotocol/server-sqlite：SQLite 数据库操作

8. 自定义命令

8.1 创建自定义斜杠命令

在 .gemini/commands/ 目录下创建 .toml 文件：

# .gemini/commands/review.toml
name = "review"
description = "Review the current changes"
prompt = """
Please review the current git diff and provide feedback:
1. Check for code quality issues
2. Suggest improvements
3. Identify potential bugs
"""

8.2 使用自定义命令

/review

9. 实用技巧

9.1 提高工作效率

使用 GEMINI.md 提供充分的项目上下文
使用自定义命令处理重复性任务
利用 MCP 集成常用开发工具
合理使用沙盒模式保护系统文件

9.2 控制成本

优先使用免费 OAuth 认证
避免不必要的 Google Search 调用
使用 -p 参数进行单次查询，避免长时间交互
监控每日使用量，接近限额时切换到 API Key

9.3 调试技巧

# 开启详细日志
export DEBUG="gemini:*"
gemini

# 查看当前配置
gemini /settings

# 检查认证状态
gemini /auth

10. 常见问题

Q：Gemini CLI 和 Gemini API 有什么区别？

A：Gemini CLI 是终端工具，内置 AI Agent 能力，可以直接操作文件系统和执行命令；Gemini API 是纯编程接口，需要自己编写代码调用。

Q：免费额度用完了怎么办？

A：可以切换到 Gemini API Key（付费层），或者等待第二天额度刷新。

Q：支持 Windows 吗？

A：支持，包括原生 Windows 和 WSL。推荐使用 WSL2 获得更好的兼容性。

Q：如何更新到最新版本？

A：运行 npm update -g @google/gemini-cli，或使用对应渠道重新安装。

Q：能否在 CI/CD 中使用？

A：可以，使用 Headless 模式配合环境变量认证，通过 -p 参数传入指令。

总结

Gemini CLI 是一个强大的终端 AI 助手，特别适合开发者日常工作：

代码理解：快速分析项目结构和代码逻辑
代码生成：根据需求生成代码片段或完整文件
代码审查：自动检查代码质量问题
文档编写：生成 README、注释等技术文档
日常问答：技术问题查询和解答

借助慷慨的免费额度和丰富的扩展能力，Gemini CLI 正在成为开发者工具箱中的新利器。

本指南基于 Gemini CLI 最新版本编写，具体功能可能随版本更新有所变化，请以官方文档为准。

杆子博客