Google Gemini CLI 完整使用指南

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

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 方式对比

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 认证相关

4.2 配置路径相关

4.3 运行时控制

4.4 settings.json 中使用环境变量

在配置文件中可以通过 $VAR_NAME 或 ${VAR_NAME:-默认值} 引用：

{
  "mcpServers": {
    "my-server": {
      "env": {
        "DATABASE_URL": "$DATABASE_URL",
        "API_TOKEN": "${MY_TOKEN:-fallback-value}"
      }
    }
  }
}

5. 命令行参数参考

5.1 启动命令

gemini [OPTIONS] [PROMPT]

5.2 常用参数

5.3 模型名称参考

在会话中切换模型：

/model gemini-2.5-flash    # 切换到 Flash
/model gemini-2.5-pro      # 切换到 Pro

5.4 常用启动场景示例

# 交互式会话
gemini

# 非交互式执行（CI 场景）
gemini -p "检查代码中的安全漏洞" --output-format json

# 指定模型
gemini -m gemini-2.5-flash "快速回答这个问题"

# Plan 模式（只读，不执行操作）
gemini --approval-mode plan

# 全自动模式（谨慎使用）
gemini --yolo "按照 TODO.md 完成所有任务"

# 带检查点（重要任务推荐）
gemini --checkpointing "重构整个 src/api 目录"

# 加入额外目录上下文
gemini --include-directories ./docs --include-directories ./specs

# 流式 JSON 输出
gemini -p "运行测试并报告结果" --output-format stream-json

6. 会话内斜杠命令（Slash Commands）

输入 / 打开命令列表，继续输入过滤。

6.1 会话管理

6.2 内容与输出

6.3 配置与信息

6.4 工具与扩展

6.5 内存与上下文

6.6 Agent 与子 Agent

6.7 工作区管理

6.8 项目初始化

6.9 自定义命令

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

# ~/.gemini/commands/plan.toml
# 使用 /plan 调用
description = "先规划，不立即实现"
prompt = """
分析需求后，只输出一个详细的分步执行计划，不要开始实现。
等待用户反馈后再继续。
"""

嵌套目录创建命名空间命令：

.gemini/commands/git/commit.toml  →  /git:commit
.gemini/commands/db/migrate.toml  →  /db:migrate

7. @ 文件引用与 ! Shell 命令

7.1 @ 文件引用

在提示词中使用 @路径 将文件或目录内容注入上下文：

# 引用单个文件
@src/api/users.ts 分析这个文件的结构

# 引用目录（自动过滤 .gitignore 和 .geminiignore 中的内容）
@src/utils/ 重构这个目录下的所有工具函数

# 引用图片
@screenshot.png 解释这个截图中的 UI 问题

# 引用 PDF
@spec.pdf 根据这个规格书生成实现代码

# 同时引用多个文件
@package.json @tsconfig.json 检查这两个配置是否有冲突

支持的文件类型：文本文件、代码文件、图片（PNG/JPG/WebP/GIF）、PDF、音频、视频

Git 感知：引用目录时，自动跳过 .gitignore 和 .geminiignore 中指定的内容。

7.2 ! Shell 命令

在提示词中用 ! 前缀直接执行 Shell 命令：

# 执行并显示结果
!ls -la src/

# 执行并让 Gemini 分析结果
!git log --oneline -20
根据上面的提交历史，总结最近的工作进展

# 进入持久 Shell 模式（单独输入 ! 切换）
!
# 现在在 Shell 模式中，直接输入命令
ls
git status
# 再次输入 ! 退出 Shell 模式
!

8. 会话内快捷键

8.1 基础控制

8.2 输入编辑

8.3 界面控制

8.4 Vim 模式

启用后支持完整 Vim 键位（/vim 命令启用）：

8.5 自定义键位绑定

在 ~/.gemini/keybindings.json 中配置（类似 VS Code 格式）：

[
  {
    "command": "workbench.action.files.save",
    "key": "ctrl+s"
  },
  {
    "command": "-clearInput",
    "key": "ctrl+u"
  }
]

9. 配置文件详解（settings.json）

配置文件位于 ~/.gemini/settings.json（用户级）或 .gemini/settings.json（项目级）。

9.1 配置优先级（从低到高）

1. 内置默认值
2. 系统默认文件（/etc/gemini-cli/system-defaults.json）
3. 用户配置文件（~/.gemini/settings.json）
4. 项目配置文件（.gemini/settings.json）
5. 系统强制配置（/etc/gemini-cli/settings.json，企业级强制覆盖）
6. 环境变量
7. 命令行参数

9.2 完整配置示例

{
  "general": {
    "preferredEditor": "code",
    "vimMode": false,
    "defaultApprovalMode": "auto_edit",
    "enableAutoUpdate": true,
    "devtools": false
  },

  "model": {
    "model": "gemini-2.5-pro",
    "temperature": 1.0,
    "topP": 0.95,
    "topK": 64,
    "thinkingBudget": 8192
  },

  "sandbox": {
    "sandbox": false
  },

  "auth": {
    "account": "your@gmail.com"
  },

  "telemetry": {
    "enabled": false,
    "logPromptsToConsole": false
  },

  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      },
      "timeout": 30000,
      "trust": false
    },
    "my-python-server": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "cwd": "./mcp_tools",
      "env": {
        "DATABASE_URL": "$DB_URL"
      },
      "includeTools": ["safe_tool_1", "safe_tool_2"],
      "excludeTools": ["dangerous_tool"]
    }
  }
}

9.3 关键配置项说明

defaultApprovalMode：

thinkingBudget：Gemini 3 扩展思考的最大 Token 数，设为 0 禁用思考，-1 为动态分配。

10. GEMINI.md 项目上下文文件

10.1 文件层级

Gemini CLI 合并多层级的 GEMINI.md 文件，具体目录越深，优先级越高：

~/.gemini/GEMINI.md                # 全局：适用于所有项目
<项目根>/GEMINI.md                 # 项目级：整个项目通用
<项目根>/src/GEMINI.md             # 子目录：src 相关规则
<项目根>/src/api/GEMINI.md         # 更精细的 API 规则

查看当前加载的所有文件：/memory list
查看合并后的完整内容：/memory show

10.2 使用 /init 自动生成

cd my-project
gemini
> /init
# Gemini 分析项目结构后生成 GEMINI.md

10.3 内容结构建议

# 项目名称 GEMINI.md

## 项目概述
一个基于 Next.js 15 + TypeScript 的 SaaS 应用。
后端：Node.js + Prisma + PostgreSQL。
部署：Vercel。

## 技术栈
- 框架：Next.js 15（App Router）
- 语言：TypeScript（严格模式）
- 数据库：PostgreSQL + Prisma ORM
- 测试：Jest + React Testing Library
- 样式：Tailwind CSS v4

## 关键命令
- 开发：`pnpm dev`
- 测试：`pnpm test`
- 构建：`pnpm build`
- 数据库迁移：`pnpm prisma migrate dev`

## 代码规范
- 函数式组件，禁止 Class 组件
- 所有新文件必须使用 TypeScript，禁止 any
- 测试覆盖率要求 ≥ 80%
- 使用 async/await，不用 .then() 链

## 文件组织
- 按功能分组：src/features/<feature>/<component>
- API 路由：src/app/api/
- 共享工具：src/lib/

## 禁止操作
- 不要直接修改 prisma/migrations/ 目录
- 不要删除 .env.example 中的字段
- 不要绕过 TypeScript 类型检查

## 导入其他说明文件
@./src/frontend/react-guidelines.md
@./src/backend/api-conventions.md

10.4 .geminiignore 文件

类似 .gitignore，排除不应被 Gemini 读取的文件：

# .geminiignore
/node_modules/
/dist/
*.log
.env
.env.local
*.secret
/backups/
coverage/

11. 常用功能详解

11.1 Plan 模式（规划模式）

只读、只规划，不执行任何写操作：

# 启动时开启
gemini --approval-mode plan

# 或在 settings.json 中设置
# "defaultApprovalMode": "plan"

使用场景：重构前先看执行计划，大型任务分析，不想意外修改文件。

11.2 Checkpointing（检查点）

每次工具调用前自动保存项目快照：

gemini --checkpointing "重构整个认证模块"

# 会话中查看检查点
/restore

# 回滚到指定检查点
/restore <checkpoint_id>

强烈推荐：进行重大代码变更前开启，等效于自动 git stash。

11.3 Headless 模式（无交互脚本模式）

# 基础用法
gemini -p "生成项目文档" --output-format text

# JSON 结构化输出
gemini -p "分析代码架构" --output-format json

# 流式 JSON（适合长时间任务的实时监控）
gemini -p "运行测试并修复失败用例" --output-format stream-json

# 管道输入
echo "解释这段代码" | gemini -p -

# 管道与文件结合
cat error.log | gemini -p "分析这个错误日志，找出根本原因" -

11.4 多模态输入

# 图片分析
gemini
> @screenshot.png 这个界面有哪些可以改进的地方

> @architecture-diagram.jpg 解释这个架构图，指出潜在的性能瓶颈

# PDF 处理
> @requirements.pdf 根据这份需求文档生成技术设计方案

# 多文件
> @before.png @after.png 对比这两个界面设计，哪个更好

11.5 Google Search 联网搜索

Gemini CLI 内置 Google Search 工具，可以直接联网获取最新信息：

> 搜索最新的 React 19 breaking changes 并告诉我如何迁移

> 查找 Next.js 15 的最新版本发布说明

> 搜索 "Node.js 22 performance improvements" 并总结要点

11.6 网页抓取

> 读取 https://docs.example.com/api-reference 并生成对应的 TypeScript 类型定义

> 抓取 https://github.com/vercel/next.js/releases/latest 并总结新功能

11.7 Token 缓存

对于重复使用相同大型上下文的场景，开启 Token 缓存可降低成本（仅 API Key 认证时有效）：

// settings.json
{
  "tokenCaching": {
    "enabled": true
  }
}

11.8 沙箱模式

在 Docker 容器或 macOS Seatbelt 中隔离执行 Shell 命令：

# 命令行开启
gemini --sandbox

# settings.json 开启
{
  "sandbox": {
    "sandbox": true
  }
}

# 自定义 macOS 沙箱规则
# 创建：.gemini/sandbox-macos-custom.sb

# 自定义 Docker 沙箱
# 创建：.gemini/sandbox.Dockerfile

11.9 会话管理（保存与恢复）

# 保存会话
/chat save my-session.md        # 保存为 Markdown
/chat save my-session.json      # 保存为 JSON

# 恢复会话
/chat resume my-session.md

# 列出历史会话（通过文件管理）
ls ~/.gemini/sessions/

11.10 Rewind（回退）

回退到上一次工具调用前的状态，不需要知道具体检查点 ID：

# 在会话中使用
/rewind

12. MCP 集成

12.1 在 settings.json 中配置

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "$DATABASE_URL"
      }
    },
    "remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer $MCP_TOKEN"
      },
      "timeout": 30000
    }
  }
}

12.2 使用 MCP 工具

配置好 MCP Server 后，在提示词中用 @server-name 调用：

# GitHub MCP
> @github 列出我最近 10 个未关闭的 PR

> @github 查找所有带有 "bug" 标签的 issues

# 数据库 MCP
> @postgres 查询 users 表中最近 7 天注册的用户数量

# Slack MCP
> @slack 把今天的代码变更摘要发送到 #dev 频道

12.3 MCP Prompts 作为自定义命令

如果 MCP Server 定义了 Prompts，它们会自动成为斜杠命令：

# MCP Server 的 "code-review" prompt 变成
/code-review --pr=123

# 带参数调用
/research --topic="React Server Components" --depth="detailed"

12.4 查看 MCP 状态

/mcp          # 列出所有 MCP 服务器及工具
/mcp desc     # 显示详细描述
/mcp reload   # 重新加载所有服务器

12.5 官方 Extensions（扩展）系统

Gemini CLI 还提供 Extension 系统，作为比 MCP 更高层的封装：

# 浏览官方扩展：https://geminicli.com/extensions/

# 通过 settings.json 安装扩展（示例）
{
  "extensions": {
    "github-extension": {
      "path": "~/.gemini/extensions/github"
    }
  }
}

13. 常用工作流程

13.1 了解陌生代码库

cd unknown-project
gemini
> 分析这个项目的整体架构，说明主要模块、数据流和关键依赖

> @src/core/ 这个核心模块是做什么的，有什么设计模式

> 找出这个项目中最复杂的 3 个文件，并解释复杂性的来源

13.2 新功能开发

gemini --checkpointing --approval-mode plan

# Step 1：先规划
> 我需要为用户系统添加双因素认证（TOTP），参考 @src/auth/ 的现有实现，
  给我一个详细的实现计划

# 确认计划后，切换到实现模式
/settings  # 修改 defaultApprovalMode 为 auto_edit

# Step 2：实现
> 按照上面的计划，先实现 TOTP 生成和验证的核心逻辑，
  放在 src/lib/totp.ts，并为其编写单元测试

# Step 3：集成
> 将 TOTP 集成到 @src/auth/login.ts 的登录流程中

# Step 4：验证
> 运行测试并确认所有用例通过

13.3 Bug 修复

gemini --checkpointing

> 我在生产环境遇到了以下错误：
[粘贴完整错误堆栈]

  请分析根本原因，查看相关的 @src/payment/ 代码

> 修复这个 bug，并为它添加一个回归测试，防止未来再次出现

13.4 代码重构

gemini --checkpointing

> 分析 @src/utils/ 目录，找出所有违反 DRY 原则的代码，
  列出重构计划（不要立即修改）

# 审查计划
> 开始执行重构，每次只改一个文件，改完告诉我再继续

# 验证
> 运行测试，确保重构没有破坏任何功能

13.5 生成文档

gemini

> 读取 @src/api/ 目录下所有路由文件，生成 OpenAPI 3.0 规范文档，
  保存为 docs/openapi.yaml

> 读取 @src/components/ 目录，为每个组件生成 Storybook 故事文件

> 根据 @src/ 的代码结构，更新 README.md 中的安装和使用说明

13.6 CI/CD 自动化

# .github/workflows/gemini-review.yml
- name: AI Code Review
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
  run: |
    gemini -p "审查 PR 中的代码变更，重点关注安全漏洞和性能问题" \
           --output-format json \
           > review-results.json

# 本地自动化脚本
gemini -p "运行测试，修复所有失败用例，不要修改测试文件本身" \
       --output-format stream-json \
       --yolo   # 只在 CI 环境中使用

13.7 数据处理

gemini

> @data/sales-2023.csv @data/sales-2024.csv
  合并这两个 CSV 文件，按月份对齐，输出为包含年度对比的新文件

> 读取 @Financial/Invoices/ 目录中所有 PDF，
  提取发票日期并将文件重命名为 YYYY-MM-DD_原文件名.pdf 格式

> @images/ 目录下的图片，使用 EXIF 数据将文件重命名为 YYYYMMDD_HHMMSS_原文件名.jpg 格式，
  没有 EXIF 数据的使用文件修改时间

14. 配额与定价

14.1 免费额度

ℹ️ 注意：配额在 Google Code Assist 和 Gemini CLI 之间共享。

14.2 查看配额使用

gemini
> /stats    # 当前会话 Token 使用量

# 或在 Google AI Studio 查看账号级配额
# https://aistudio.google.com/usage

14.3 付费扩展

• • Google AI Pro/Ultra 个人订阅：更高的请求配额
• • Google Cloud Vertex AI：企业级配额，按 Token 计费
• • Gemini Code Assist Standard/Enterprise：团队配额共享

15. 使用规范与注意事项

15.1 安全注意事项

认证安全：

• • 永远不要将 API Key 硬编码在代码或脚本中
• • 不要提交含有 API Key 的 .env 文件
• • 在 .geminiignore 中排除所有包含凭证的文件
• • 如果意外暴露了 API Key，立即在 Google AI Studio 中撤销并重新生成

环境变量陷阱：

• • GOOGLE_API_KEY、GEMINI_API_KEY、GOOGLE_GENAI_USE_VERTEXAI 会覆盖 OAuth 登录
• • 想用免费 OAuth 时，确保这些变量没有被设置：

  unset GOOGLE_API_KEY GEMINI_API_KEY GOOGLE_GENAI_USE_VERTEXAI

Yolo 模式风险：

• • --yolo 会跳过所有确认提示，可能删除文件、执行危险命令
• • 生产机器上禁止使用 --yolo
• • 重要任务配合 --checkpointing 使用

15.2 文件操作注意事项

• • 始终开启检查点（--checkpointing）进行大范围文件修改
• • 修改前通过 --approval-mode plan 先看执行计划
• • 用 .geminiignore 排除不应被修改的目录（如 node_modules、dist、.git）
• • Gemini CLI 遵循 .gitignore 规则，不会读取被忽略的文件

15.3 上下文窗口管理

• • Gemini 2.5 Pro 支持 100 万 Token 上下文，但超大上下文会减慢响应速度
• • 长会话中使用 /compress 压缩历史，节省 Token
• • 使用 /stats 监控当前 Token 使用量
• • 不相关的大文件不要用 @ 引入，保持上下文精准

15.4 数据隐私

• • 敏感代码、商业机密代码在使用 OAuth 模式时会发送到 Google 服务器
• • 企业用户应使用 Vertex AI 并启用数据保护协议
• • 通过 /privacy 命令了解并配置数据收集选项
• • 可通过 --telemetry disabled 关闭遥测

15.5 Windows 注意事项

• • Windows 原生支持，无需 WSL（但 WSL 体验更稳定）
• • 路径分隔符使用 \ 或 / 均可
• • 推荐使用 Windows Terminal 或 PowerShell 7+

16. 使用技巧

技巧一：提供完成标准

# ❌ 模糊
> 修复登录 bug

# ✅ 精确，带完成标准
> 修复 src/auth/login.ts 中的登录 bug。
  完成标准：
  1. `pnpm test -- auth` 全部通过
  2. 没有新的 TypeScript 错误
  3. 不要修改 auth.test.ts 中的测试用例

技巧二：用 /init 快速生成项目上下文

# 进入项目后第一件事
/init
# 然后根据实际情况编辑生成的 GEMINI.md

技巧三：@导入实现模块化 GEMINI.md

主文件保持简洁，用 @ 导入各模块的详细规范：

# GEMINI.md 主文件
@./docs/coding-standards.md
@./docs/api-conventions.md
@./docs/testing-requirements.md

技巧四：Plan 模式先规划后确认

对于复杂任务，先用 Plan 模式确认方向：

gemini --approval-mode plan
> 重构整个支付模块

# 看到计划后确认无误，再切换到执行模式
/settings  # 改为 auto_edit

技巧五：善用 /compress 控制 Token

# 长会话中，定期压缩
/compress
# Gemini 用摘要替换完整历史，继续任务

技巧六：Checkpointing + Rewind 的黄金组合

gemini --checkpointing

# 出现问题时
/rewind          # 回退到上一步
# 或
/restore         # 查看所有检查点，选择回退点

技巧七：多目录工作区

gemini
> /directory add ~/shared-libs
> /directory add ~/docs-repo

# 现在可以跨仓库引用
> @~/shared-libs/auth-utils/ 参考这个共享库，实现我们项目的认证功能

技巧八：自定义斜杠命令封装常用提示词

# ~/.gemini/commands/commit.toml
description = "生成 Conventional Commits 格式的提交信息"
prompt = """
分析当前 git diff（运行 git diff --staged），
生成符合 Conventional Commits 规范的提交信息。
格式：<type>(<scope>): <subject>

types: feat, fix, docs, style, refactor, test, chore
要求：主题行不超过 72 字符，用中文描述
"""

技巧九：利用 Google Search 获取最新信息

Gemini 的训练数据有截止日期，使用内置搜索工具获取最新内容：

> 搜索 Prisma 6 的最新迁移指南，然后帮我把项目从 Prisma 5 升级

技巧十：对大型代码库使用 Flash 节省成本

# 探索阶段用 Flash（便宜快速）
gemini -m gemini-2.5-flash "帮我理解这个项目的整体结构"

# 复杂实现用 Pro
gemini -m gemini-2.5-pro "实现这个复杂的算法"

技巧十一：使用 MCP 打通外部系统

# 配置 GitHub MCP 后，直接操作 PR
> @github 列出所有带 "needs-review" 标签的 PR，
  对每个 PR 做一个简短的代码评审摘要

# 配置数据库 MCP 后，直接查询
> @postgres 找出最近 7 天活跃的用户，
  分析他们的行为模式，生成一份报告

17. 快速参考卡

安装与认证

# 安装
npm install -g @google/gemini-cli

# 启动（首次会引导认证）
gemini

# 使用 API Key
export GEMINI_API_KEY="your-key"
gemini

常用启动参数

gemini -p "单次任务"              # 无交互执行
gemini -m gemini-2.5-flash       # 指定模型
gemini --approval-mode plan      # 规划模式
gemini --checkpointing           # 开启检查点
gemini --yolo                    # 全自动（危险）
gemini --output-format json      # JSON 输出

高频斜杠命令

/clear          清空对话和屏幕
/compress       压缩对话历史
/model          切换模型
/memory show    查看当前上下文
/memory add     添加记忆
/restore        回滚到检查点
/rewind         撤销上一次工具操作
/checkpoints    列出检查点
/mcp            查看 MCP 服务器
/tools          查看可用工具
/stats          查看 Token 用量
/settings       打开配置编辑器
/init           生成 GEMINI.md
/help           显示帮助
/quit           退出

输入语法

@文件路径        引用文件内容
@目录路径        引用目录内容（Git 感知）
!命令            执行 Shell 命令
!                切换持久 Shell 模式
/命令            斜杠命令

关键环境变量

GEMINI_API_KEY            # Gemini API Key
GOOGLE_API_KEY            # Google Cloud API Key
GOOGLE_GENAI_USE_VERTEXAI # 使用 Vertex AI 后端
GOOGLE_CLOUD_PROJECT      # GCP 项目 ID
GOOGLE_APPLICATION_CREDENTIALS  # ADC 凭证路径

免费配额

GEMINI.md 层级

~/.gemini/GEMINI.md        全局
<项目根>/GEMINI.md          项目
<子目录>/GEMINI.md          模块

文档整理自 Gemini CLI 官方文档^[1] 及 GitHub 仓库^[2] · 最后更新：2026 年 4 月

引用链接

[1] Gemini CLI 官方文档: https://geminicli.com/docs/
[2] GitHub 仓库: https://github.com/google-gemini/gemini-cli