Google Gemini CLI 的安装与配置完全指南

本指南将详细介绍如何在 macOS 操作系统上安装和配置 Google 的 Gemini 命令行界面工具（CLI），包括逐步安装说明、身份验证方法以及常见的故障排除提示。

什么是 Gemini CLI？

Gemini CLI 是 Google Gemini 团队专为开发者打造的开源命令行 AI 工具（CLI）。它能够理解代码、执行复杂查询、自动化任务，并利用 Gemini 强大的多模态能力（如图像识别）生成创意内容。

主要功能

处理大型代码库：支持超过 100 万个 token 的上下文长度，能够深入分析大型项目，协助开发者理解和重构代码。
多模态应用原型生成：通过输入 PDF 文档或草图，快速生成应用程序原型，加速开发进程。
DevOps 任务自动化：自动化执行常见的 DevOps 任务，例如 Git 操作、Pull Request（PR）查询、代码迁移规划等。
外部工具集成：通过 MCP 服务器连接到 Imagen、Veo 和 Lyria 等媒体生成模型，扩展其应用场景。
内置网络搜索支持：集成 Google 搜索功能，确保 AI 回答基于最新的信息，提供实时且准确的响应。

系统要求

在 macOS 上安装 Gemini CLI 之前，请确保您的系统满足以下先决条件：

macOS 的先决条件

Node.js：版本 18.0.0 或更高。（可通过 node -v 命令检查当前版本）。
npm：Node.js 包管理器，建议使用最新版本（通常随 Node.js 一起安装）。

macOS 安装方法

Gemini CLI 提供了两种安装方式，您可以根据需要选择：、

方法 1：直接执行（无需安装）

如果您只想快速尝试 Gemini CLI 而不进行全局安装，可以直接使用 npx 运行：

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

方法 2：全局安装（推荐）

对于日常使用，建议在您的 Mac 上全局安装 Gemini CLI，这样可以在任何终端路径下直接调用 gemini 命令：

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

# 如果遇到权限问题，请使用 sudo
sudo npm install -g @google/gemini-cli

# 适用于 Apple Silicon Macs (M1/M2/M3 等)
# 如果您使用的是 Apple Silicon 芯片的 Mac，建议使用以下命令以确保兼容性：
arch -arm64 npm install -g @google/gemini-cli

# 验证安装
# 安装完成后，您可以通过以下命令验证 Gemini CLI 是否成功安装及其版本：
gemini --version
# 查看 gemini 命令的安装路径：
which gemini

初次设置指南

安装完成后，首次运行 Gemini CLI 将引导您完成简单的设置过程：

步骤 1：选择主题风格

首次在终端中运行 gemini 命令时，系统会提示您选择一个主题。您可以选择默认主题或任何其他可用选项，然后按 Enter 键继续。

步骤 2：选择身份验证方法

接下来，您将被要求选择一种身份验证方法。推荐选项是**“使用 Google 登录”，它通常提供每分钟 60 次请求和每天 1000 次请求的免费额度**。选择您偏好的方法，然后按 Enter 键。

步骤 3：浏览器授权

确认选择后，您的默认浏览器将自动打开，引导您使用 Google 帐户登录并授权。如果遇到“localhost 拒绝连接”错误，请检查您的网络连接配置，确保没有代理或防火墙阻止本地连接，然后重试。

身份验证方法详解

Gemini CLI 支持两种主要的身份验证方式：

方法 1：Google 登录（推荐）

这是最简单也是推荐的方法，适用于大多数个人开发者和小型项目，因为它包含了免费额度。

# 运行以下命令启动 Google 登录流程
gemini auth login

方法 2：API 密钥（适用于更高的使用限制）

如果您需要更高的请求频率、更稳定的服务或企业级访问权限，可以通过 Google AI Studio 创建并使用 API 密钥：

# 首先，访问 Google AI Studio 获取您的 API 密钥。
# 获取后，将 API 密钥设置为环境变量。请将 `your-api-key-from-google-ai-studio` 替换为您实际的密钥。
export GEMINI_API_KEY="your-api-key-from-google-ai-studio"

# 测试身份验证
# 设置完 API 密钥后，您可以立即尝试发送一个查询来验证身份是否成功。
gemini "Hello, Gemini!"

快速入门指南

安装并认证完成后，您就可以立即开始使用 Gemini CLI 了：

# 启动交互式会话
# 运行此命令将进入一个交互式模式，您可以持续与 Gemini AI 进行对话。
gemini

# 提出直接问题
# 您可以直接在命令行中提出问题，Gemini 会立即给出回答。
gemini "What's the capital of France?"

# 在查询中包含本地文件
# Gemini CLI 支持引用本地文件作为上下文输入。使用 `@` 符号选择文件路径。
gemini "Explain this code" @path/to/yourfile.js

# 获取可用命令的帮助
# 如果您不确定某个命令如何使用，可以使用 `help` 命令获取帮助信息。
gemini help

在 VSCode 中使用 Gemini CLI

Gemini CLI 可以与 VSCode 的集成终端无缝协作。启动 VSCode，打开内置终端（Terminal），然后直接使用 gemini 命令启动 Gemini CLI。您可以使用 @ 命令从当前工作区中选择文件，从而获得上下文感知的 AI 协助，极大地提升开发效率。

高级用法提示

在 Gemini CLI 的交互模式中，键入 / 字符可以查看所有可用的命令和快捷方式，这对于探索其功能非常有帮助。

此外，Gemini CLI 具备智能的网络适应能力。如果遇到网络问题，它将自动从默认的 gemini-2.5-pro 模型切换到 gemini-2.5-flash 模型，以提供更快速的响应和更好的性能，确保您的工作不中断。

故障排除

在使用 Gemini CLI 的过程中，您可能会遇到一些常见问题。以下是一些解决方案：

Mac 上的常见问题

权限错误（Permission Errors）：如果在安装或执行命令时遇到权限问题，通常是因为 Node.js 或 npm 的安装路径需要管理员权限。
```
sudo npm install -g @google/gemini-cli
```
身份验证失败（Authentication Failed）：请确保您有稳定的互联网连接。如果正在使用 VPN，请尝试切换到全局代理模式或暂时关闭 VPN 后重试。有时，网络环境的限制会导致认证流程无法完成。
Node.js 版本问题（Node.js Version Issues）：如果您的 Node.js 版本过旧或不兼容，可能会导致问题。您可以使用 Homebrew 轻松安装或更新 Node.js 到推荐版本：
```
brew install node@18
# 确保使用正确的 Node.js 版本：
brew link node@18 --force --overwrite
```
路径问题（Path Issues）：有时 gemini 命令可能无法在任何路径下识别，这通常是由于环境变量 PATH 未正确配置。您可以将 npm 全局包的路径添加到您的 shell 配置文件中（如 ~/.zshrc 或 ~/.bashrc）：
```
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
# 然后刷新配置
source ~/.zshrc
```

后续步骤

恭喜您！您已成功在 Mac 上安装并配置了 Gemini CLI。现在，您可以继续学习官方的入门指南以了解基础知识，或查阅命令参考以获取完整的命令列表，进一步探索 Gemini CLI 的强大功能。

关于

关注我获取更多资讯

📢 公众号

💬 个人号