Gemini CLI 新手入门指南

约 1989 字大约 7 分钟...

Gemini CLI 是由 Google 推出的一款开源 AI 编程助手，它将 Google 最先进的 Gemini AI 模型直接带到你的命令行终端中。作为一个完全开源的项目（Apache 2.0 许可），Gemini CLI 不仅提供强大的代码理解和生成能力，还支持丰富的扩展生态系统，包括与 VS Code 的深度集成、GitHub Actions 自动化，以及通过 MCP（模型上下文协议）的无限扩展可能性。本指南将带你从零开始，一步步掌握这个强大的 AI 编程工具。

第一步：快速安装 Gemini CLI

Gemini CLI 的安装过程非常简单，我们提供了多种安装方式来适应不同的使用习惯。

检查先决条件

首先确保你的系统已安装 Node.js 20 或更高版本：

node --version

如果没有安装或版本过低，请访问 nodejs.org 下载最新的 LTS 版本。

选择安装方式

方式一：快速体验（无需安装）

如果你想先试用一下，可以直接运行：

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

方式二：全局安装（推荐）

对于日常使用，建议全局安装：

npm install -g @google/gemini-cli

方式三：通过 Homebrew（macOS/Linux）

如果你使用 macOS 或 Linux，也可以通过 Homebrew 安装：

brew install gemini-cli

验证安装

安装完成后，运行以下命令验证：

gemini --help

如果看到详细的帮助信息，说明安装成功！

第二步：选择认证方式

Gemini CLI 提供了多种认证方式，你可以根据自己的需求选择最合适的。

方式一：OAuth 登录（推荐个人用户）

这是最简单的方式，适合个人开发者：

在终端运行：
```
gemini
```
首次运行时，Gemini CLI 会：
- 自动打开你的默认浏览器
- 引导你登录 Google 账户
- 完成授权后自动返回终端
登录成功后，你将获得慷慨的免费额度：
- 每分钟 60 次请求
- 每天 1000 次请求
- 使用 Gemini 2.5 Pro 模型

方式二：API 密钥（适合脚本化使用）

如果你需要在脚本中使用或想要更多控制：

访问 Google AI Studio 获取免费 API 密钥
设置环境变量：
```
export GEMINI_API_KEY="你的API密钥"
```
或者在项目目录创建 .gemini/.env 文件：
```
GEMINI_API_KEY=你的API密钥
```

gemini

你会看到一个友好的欢迎界面。现在你可以用自然语言与 AI 对话了！

尝试这些基础命令

代码解释：

请解释这个项目的主要功能

代码生成：

帮我写一个 JavaScript 函数来验证邮箱格式

文件分析（使用 @ 符号引用文件）：

分析 @./src/main.js 这个文件的代码质量

一次性命令模式

如果你只想执行一个快速任务：

gemini -p "重构这个函数使其更易读"

第四步：配置项目上下文

Gemini CLI 的强大之处在于它能理解你的整个项目上下文。通过 GEMINI.md 文件，你可以为 AI 提供项目的"记忆"。

创建项目上下文文件

在你的项目根目录创建 GEMINI.md 文件：

# MyWebApp 项目指南

## 技术栈

- 前端：React + TypeScript + Vite
- 后端：Node.js + Express
- 数据库：MongoDB
- 样式：Tailwind CSS

## 编码规范

- 使用 Prettier 进行代码格式化
- 所有函数必须有 TypeScript 类型注解
- 组件名使用 PascalCase
- 文件名使用 kebab-case

## 项目结构

- `/src/components/` - React 组件
- `/src/hooks/` - 自定义 Hooks
- `/src/utils/` - 工具函数
- `/src/api/` - API 调用

## 开发流程

- 新功能在 feature 分支开发
- 所有 PR 必须通过代码审查
- 部署前必须通过所有测试

查看和管理项目记忆

在交互模式中，你可以使用这些命令：

/memory show - 查看当前加载的所有项目上下文
/memory add "新规则" - 动态添加新的项目规则

多层级上下文合并

Gemini CLI 会智能地合并多个层级的上下文文件：

全局上下文：~/.gemini/GEMINI.md
父目录上下文：向上搜索所有父目录
项目根目录：./GEMINI.md
子目录上下文：当前工作目录的特定规则

第五步：启用安全功能 - 检查点系统

Gemini CLI 提供了强大的检查点功能，在 AI 修改文件前自动创建快照，让你可以安全地回滚任何更改。

启用检查点

方法一：命令行启用

gemini --checkpointing

方法二：配置文件启用

创建 ~/.gemini/settings.json 文件：

{
  "checkpointing": {
    "enabled": true
  },
  "theme": "GitHub",
  "autoAccept": false,
  "fileFiltering": {
    "respectGitIgnore": true
  }
}

使用检查点

当检查点启用后：

AI 修改文件前会自动创建快照
在交互模式中输入 /restore 查看所有可用的检查点
使用 /restore <检查点文件名> 回滚到指定状态

第六步：掌握高级功能

常用斜杠命令

在交互模式中，这些命令会让你的工作更高效：

/help - 显示所有可用命令
/auth - 切换认证方式
/tools - 查看所有可用工具
/mcp - 列出已安装的扩展
/stats - 查看 Token 使用统计

高级配置选项

编辑 ~/.gemini/settings.json 来自定义你的体验：

{
  "theme": "GitHub",
  "autoAccept": false,
  "checkpointing": { "enabled": true },
  "fileFiltering": { "respectGitIgnore": true },
  "excludeTools": ["run_shell_command(rm)"],
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "你的 GitHub 令牌"
      }
    }
  }
}

扩展生态系统（MCP）

Gemini CLI 支持模型上下文协议（MCP），你可以安装各种扩展来增强功能：

GitHub 集成
数据库连接
文件系统增强
自定义工具

了解使用成本

免费额度

Gemini CLI 提供了非常慷慨的免费额度：

认证方式	模型	免费限制
OAuth	Gemini 2.5 Pro	60 次/分钟，1000 次/天
API Key	Gemini 2.5 Pro	100 次/天

付费使用

当你需要更多使用量时，可以查看 Google AI 的定价：

Gemini 2.5 Pro：输入 $1.25/百万 Token，输出 $10/百万 Token
Gemini 2.5 Flash：输入 $0.30/百万 Token，输出 $2.50/百万 Token

监控使用量

在交互模式中使用 /stats 命令随时查看你的 Token 使用情况。

常见问题解答

Q: Gemini CLI 完全免费吗？ A: 是的！对于个人开发者，免费额度通常足够日常使用。

Q: 我的代码会被发送到 Google 吗？ A: 是的，Gemini CLI 需要将代码发送到 Google 的服务器进行处理。请确保遵守你的公司政策。

Q: 如何确保文件修改的安全性？ A: 强烈建议启用检查点功能，并在重要项目中使用 Git 进行版本控制。

Q: 可以离线使用吗？ A: 不可以，Gemini CLI 需要网络连接来访问 Google 的 AI 服务。

Q: 支持哪些编程语言？ A: Gemini CLI 支持几乎所有主流编程语言，包括 Python、JavaScript、Java、C++、Go 等。

下一步探索

现在你已经掌握了 Gemini CLI 的基础使用，可以尝试：

VS Code 集成：安装官方 VS Code 扩展，享受更丰富的编辑体验
GitHub Actions：在 CI/CD 流程中集成 Gemini CLI 进行自动化代码审查
MCP 扩展：探索社区开发的各种扩展插件
团队协作：与团队成员分享 GEMINI.md 配置，统一开发规范

参考资料

Google Cloud Gemini CLI 文档
Gemini API 快速开始
Gemini API 定价 (https://ai.google.dev/gemini-api/docs/pricing)