Gemini CLI 安装配置教程：从零开始使用Google AI终端编程助手

Google 推出的 Gemini CLI 是一款基于 AI 的终端编程助手，能够帮助开发者在命令行中完成代码分析、文档生成、Bug 修复等任务。本文基于 Real Python 的视频教程，详细介绍 Gemini CLI 的安装、配置和首次使用流程，帮助你快速将这款工具融入日常编码工作流。

什么是 Gemini CLI

Gemini CLI 是 Google 面向开发者推出的 AI 编程助手，直接运行在终端环境中。与传统的 IDE 插件不同，它在命令行中工作，能够分析项目结构、理解代码上下文，并以对话的方式回答开发者的问题。

需要注意的是，"Gemini" 严格来说是指底层的 AI 模型，而 "Gemini CLI" 才是这款命令行编程助手的正式名称。不过在日常使用中，很多人会直接简称为 Gemini。Gemini 是 Google DeepMind 于 2023 年底推出的多模态大语言模型家族，它统一了此前 Google 在 AI 领域的多条产品线——包括面向消费者的 Bard 聊天机器人和底层的 PaLM 2 模型。Gemini 模型家族包含多个版本：Ultra 面向最复杂的推理任务，Pro 提供性能与效率的平衡，Flash 专注于低延迟高吞吐的场景，Nano 则针对端侧设备进行了优化。Gemini CLI 默认使用的是 Gemini 2.5 Pro 模型，这是目前 Google 在代码理解和生成方面表现最强的版本之一，具备超长上下文窗口（最高支持 100 万 token），这也是它能够分析大型项目代码库的技术基础。

Gemini CLI 提供了免费使用的模型选项，但你必须拥有一个 Google 账号才能使用。由于 AI 工具更新频繁，建议随时查阅官方文档 geminicli.com 获取最新信息。

Gemini CLI 官方文档

安装 Gemini CLI

前置条件：安装 Node.js

Gemini CLI 使用 TypeScript 开发，因此运行它需要 Node.js 环境。TypeScript 是微软开发的 JavaScript 超集语言，它在 JavaScript 的基础上添加了静态类型系统和更丰富的面向对象特性。近年来，越来越多的命令行工具选择使用 TypeScript 开发，原因在于它兼具 JavaScript 生态的丰富性和强类型语言的可维护性。而 Node.js 则是让 JavaScript 能够脱离浏览器、在服务端和本地环境运行的运行时引擎，它基于 Chrome 的 V8 引擎构建，提供了文件系统访问、网络通信等操作系统级别的能力。Gemini CLI 正是借助 Node.js 运行时来实现终端交互、文件读取和网络请求等核心功能。

在安装之前，先在终端中检查 Node.js 版本：

node --version

确保版本号高于 v20。如果尚未安装 Node.js，macOS 或 Linux 用户可以通过 Homebrew 安装，也可以前往 Node.js 官方下载页面获取安装包。对于需要管理多个 Node.js 版本的开发者，推荐使用 nvm（Node Version Manager）工具，它类似于 Python 生态中的 pyenv，可以方便地在不同版本之间切换。

通过 npm 全局安装 Gemini CLI

确认 Node.js 就绪后，使用以下命令全局安装 Gemini CLI：

npm install -g @google/gemini-cli

这里的 npm（Node Package Manager）类似于 Python 生态中的 pip/PyPI，是 JavaScript 世界的包管理器。npm 注册表（registry）托管了超过 200 万个开源包，是目前全球最大的软件注册表之一。命令中的 @google/ 前缀表示这是 Google 组织下的官方包，这种命名空间机制（称为 scoped packages）可以有效避免包名冲突，同时也方便用户识别包的来源和可信度。-g 参数表示全局安装，即将可执行文件放置在系统 PATH 中，安装完成后你可以在系统的任何目录下使用 gemini 命令。

安装完成后，验证是否安装成功：

gemini --version

教程录制时的版本为 0.13.0，但由于 AI 工具迭代速度很快，你看到的版本号可能已经更高。核心功能不会有太大变化，如果遇到问题建议查阅官方文档。

Gemini CLI 安装说明

账号认证与登录

安装完成后，在终端输入 gemini 启动程序。首次运行时，你会看到一个欢迎界面，并提供三种认证方式：

Log in with Google — 使用 Google 账号登录（推荐）
Use Gemini API Key — 使用 API 密钥
Vertex AI — 使用 Google Cloud 的 Vertex AI

对于大多数用户来说，第一种方式最为便捷。选择后按回车，系统会自动打开默认浏览器，引导你登录 Google 账号。这个过程背后使用的是 OAuth 2.0 授权协议中的设备授权流程（Device Authorization Flow）。由于命令行工具本身没有图形界面，无法直接展示登录表单，因此它会将认证过程委托给浏览器完成。具体流程是：CLI 向 Google 的授权服务器请求一个设备码，然后引导用户在浏览器中访问授权页面并确认授权，授权成功后 CLI 会自动获取访问令牌（Access Token）。这种方式的安全优势在于，你的 Google 密码始终只在浏览器中输入，永远不会经过 CLI 工具本身，大大降低了凭据泄露的风险。第二种 API Key 方式更适合自动化脚本和 CI/CD 流水线场景，而 Vertex AI 则面向已经在使用 Google Cloud Platform 的企业用户，它支持更细粒度的访问控制和企业级安全策略。

登录成功后，浏览器会显示 "Authentication successful" 的提示信息，切换回终端即可看到交互提示符，表示已经准备就绪。

Gemini CLI 认证流程

如何退出 Gemini CLI

退出 Gemini CLI 有两种方式：

输入 /quit 命令
连续按两次 Ctrl + C

退出时，Gemini CLI 会显示一段统计信息，包括当前会话 ID、API 调用次数、成功率等数据。这对于关注使用量和成本的开发者来说非常实用。值得一提的是，Gemini CLI 的免费额度是按照每分钟请求数（RPM）和每日请求数来计算的，而非简单的 token 总量限制，因此了解自己的调用频率有助于避免触及速率限制。

Gemini CLI 退出时的统计信息

测试你的第一个提示

准备项目环境

为了让学习过程更贴近实际开发场景，教程提供了一个 To-Do List 项目作为练习素材。在启动 Gemini CLI 之前，确保终端已经切换到项目目录：

cd path/to/gemini-todo-list
gemini

每次在新目录中启动 Gemini CLI 时，它会首先分析项目结构并索引文件以建立上下文。这个过程涉及多个技术环节：首先，CLI 会递归扫描项目目录，识别源代码文件、配置文件、依赖声明文件等关键文件；然后，它会读取这些文件的内容并构建一个项目的"知识图谱"，包括文件之间的引用关系、模块结构、使用的框架和库等信息。这些信息会被整理成结构化的上下文（context），在后续的每次对话中作为提示词（prompt）的一部分发送给 Gemini 模型。正是这种上下文注入机制，使得 AI 能够给出与你的具体项目高度相关的回答，而不是泛泛而谈的通用建议。项目越大，需要索引的文件越多，首次启动所需的时间越长。你可以通过提示符下方显示的路径信息确认当前工作目录是否正确。

向 Gemini CLI 发送第一个提示

一个好的起始问题应该既能验证连接是否正常，又能帮助你快速了解项目概况。例如：

What programming language is this project written in?

Gemini CLI 会迅速分析项目文件并给出回答：

This project appears to be written in Python, indicated by the .py file extension and the pyproject.toml file.

这个回答不仅准确，还说明了判断依据——.py 文件扩展名和 pyproject.toml 配置文件。其中 pyproject.toml 是 Python 社区在 PEP 518（2016 年）和 PEP 621（2020 年）中引入的标准化项目配置文件格式。在此之前，Python 项目的元数据和构建配置分散在 setup.py、setup.cfg、requirements.txt 等多个文件中，缺乏统一标准。pyproject.toml 使用 TOML（Tom's Obvious Minimal Language）格式，将项目名称、版本、依赖、构建系统等信息集中在一个文件中管理。现代 Python 构建工具如 Poetry、Hatch、PDM 以及最新版本的 pip 和 setuptools 都已全面支持这一格式。Gemini CLI 能够识别 pyproject.toml 并据此判断项目语言，说明它对现代 Python 项目的工具链有着准确的理解。

这个简单的测试证明了两件事：

Gemini CLI 与 Google AI 模型的通信正常
它能够有效地分析和理解项目文件结构

实用建议与注意事项

免费额度与使用限制

Gemini CLI 提供部分模型的免费使用额度，但具体限制可能随时调整。截至目前，使用个人 Google 账号登录时，Gemini CLI 提供每分钟 60 次请求、每天 1000 次请求的免费额度，这对于个人开发者的日常使用来说已经相当充裕。如果需要更高的配额或企业级功能，可以通过 Vertex AI 方式接入并使用付费计划。建议关注退出时显示的调用统计，合理规划使用量。

项目上下文感知能力

Gemini CLI 的一大优势在于它的项目上下文感知能力。它不仅仅是一个通用的 AI 聊天工具，而是能够深入理解你当前项目的结构、依赖和代码逻辑。这种能力的核心在于大语言模型的长上下文窗口技术——Gemini 2.5 Pro 支持最高 100 万 token 的上下文窗口，这意味着它可以一次性"阅读"数十万行代码并保持对整个代码库的理解。相比之下，早期的 GPT-3.5 仅支持 4096 token 的上下文窗口，根本无法处理中等规模以上的项目。这使得 Gemini CLI 在以下场景中特别有用：

代码库探索：快速了解一个陌生项目的技术栈和架构，特别适合新加入团队或接手遗留项目的开发者
文档生成：基于代码自动生成项目文档，包括 API 文档、README、架构说明等
Bug 排查：结合上下文定位和修复代码缺陷，它能够理解跨文件的调用链和数据流，给出更精准的修复建议
代码重构：分析现有代码结构并提出重构方案，帮助改善代码质量
测试生成：根据现有代码逻辑自动生成单元测试用例

Gemini CLI 与其他 AI 编程工具的区别

相比 GitHub Copilot 等 IDE 内嵌的 AI 助手，Gemini CLI 更适合习惯在终端中工作的开发者。它不需要特定的编辑器支持，在任何终端环境中都能运行，对于远程服务器开发、DevOps 场景尤其方便。

当前终端 AI 编程助手的市场正在快速发展，除了 Gemini CLI 之外，还有多款值得关注的竞品。Claude Code 是 Anthropic 推出的终端编程助手，基于 Claude 模型，以出色的代码理解和长文本处理能力著称。Aider 是一款开源的终端 AI 编程工具，支持接入多种模型（包括 GPT-4、Claude、本地模型等），它的特色在于能够直接对 Git 仓库中的文件进行编辑并自动生成 commit。GitHub Copilot CLI 则是 GitHub Copilot 的命令行扩展，专注于帮助用户生成和解释 shell 命令。Cursor 虽然是一款 IDE 而非纯终端工具，但它深度集成了 AI 能力，代表了另一种"AI 原生编辑器"的发展方向。

与这些工具相比，Gemini CLI 的核心优势在于：免费额度慷慨、背靠 Google 的 Gemini 模型（尤其是超长上下文窗口）、以及与 Google 生态（如 Google Cloud、Firebase）的天然集成能力。而它的主要局限在于目前仅支持 Gemini 模型，不像 Aider 那样可以灵活切换不同的 AI 后端。选择哪款工具，最终取决于你的具体需求、工作流偏好和所使用的技术栈。

总结

Gemini CLI 为终端开发者提供了一个轻量但强大的 AI 编程助手。从安装到首次使用，整个流程非常简单：只需 Node.js 环境和一个 Google 账号，几分钟内即可开始使用。它的项目上下文分析能力使其不仅仅是一个问答工具，更是一个能够深入理解你代码的智能伙伴。如果你是一个终端重度用户，Gemini CLI 值得一试。

核心要点

Gemini CLI 是 Google 推出的基于 AI 的终端编程助手，底层使用 Gemini 2.5 Pro 模型，支持免费使用部分模型，但需要 Google 账号认证
安装需要 Node.js v20+ 环境，通过 npm install -g @google/gemini-cli 全局安装
首次在项目目录启动时会自动分析项目结构并建立上下文索引，借助 Gemini 模型的超长上下文窗口实现项目感知能力
支持三种认证方式（Google 账号、API Key、Vertex AI），其中 Google 账号登录基于 OAuth 2.0 协议最为便捷，退出时会显示调用次数等使用统计
适合终端重度用户，可用于代码库探索、文档生成和 Bug 修复等场景，与 Claude Code、Aider 等工具形成互补的终端 AI 工具生态