# 如何在 Ubuntu 上安装 Gemini CLI：完整分步教程

在 Ubuntu 上安装 Google Gemini CLI 的分步教程。涵盖 Node.js 20+ 设置、npm 全局安装、身份验证、验证以及解决 Ubuntu LTS 上的常见问题。

Canonical URL: https://a2a-mcp.org/blog/how-to-install-gemini-cli-on-ubuntu-zh

Language: zh

Published: 2026-04-07

Updated: 2026-04-07

## 前置条件

在 Ubuntu 上开始安装 Gemini CLI 前，请准备好以下事项：

-gemini模型
- **Ubuntu 版本**：20.04 LTS 或更高版本（22.04、24.04 和 26.04 完全支持）。
- **管理员权限**：用于软件包管理的 Sudo 权限。
- **网络连接**：需要用于下载 Node.js、npm 包和进行身份验证。
- **Google 账号**：用于通过 OAuth 登录以访问 Gemini 模型。
- **推荐硬件**：至少 4 GB 内存和 2 个 CPU 核心，以确保交互会话期间的流畅性能。

**假定基础知识**：您知道如何打开终端并运行基本的 `apt` 和 `bash` 命令。

## 步骤 1：更新系统软件包

首先刷新软件包列表并升级现有软件包，以防止依赖冲突：

```bash
sudo apt update && sudo apt upgrade -y
```

此步骤确保您拥有最新的安全更新和仓库信息。

## 步骤 2：安装 Node.js 20 或更高版本

Gemini CLI 需要 **Node.js 版本 20 或更新**。Ubuntu 的默认仓库通常包含较旧版本（例如，Ubuntu 24.04 上的 Node 18）。

### 推荐方法：NodeSource 仓库

```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
```

### 替代方案：使用 nvm (Node 版本管理器)

为了方便版本管理：

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
nvm alias default 20
```

验证安装：

```bash
node --version
npm --version
```

您应该会看到类似 `v20.x.x` 的 Node.js 输出和匹配的 npm 版本。

## 步骤 3：安装 Gemini CLI

### 全局安装（推荐用于日常使用）

```bash
npm install -g @google/gemini-cli
```

这使得 `gemini` 命令可在整个系统范围内使用。

### 快速测试（无需永久安装）

如果您想先试用一下：

```bash
npx @google/gemini-cli
```

### 用户级安装（避免权限问题）

如果在全局安装时遇到权限错误：

```bash
mkdir -p ~/.local/bin
npm config set prefix '~/.local'
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli
```

## 步骤 4：验证安装

检查 Gemini CLI 是否正确安装：

```bash
gemini --version
```

预期输出将显示 Gemini CLI 的当前版本。

## 步骤 5：启动并验证身份

首次运行 CLI：

```bash
gemini
```

该工具将提示您使用 Google 登录。浏览器窗口会自动打开。完成 OAuth 流程并返回终端。

成功验证身份后，将加载交互式 Gemini CLI 界面。使用 `/help` 查看可用命令。

**最佳实践**：在启动前导航到您的项目目录：

```bash
cd ~/my-project
gemini
```

## 常见问题与故障排除

- **‘gemini: command not found’**: 重启终端或运行 `source ~/.bashrc`。使用 `echo $PATH` 检查你的 PATH 变量。

- **`npm install` 时权限被拒绝**: 使用上文提到的用户级别安装方法，而不是 `sudo npm`。

- **Node.js 版本错误**: 重新运行 NodeSource 设置或使用 nvm 切换版本。使用 `node --version` 确认版本。

- **身份验证失败**: 禁用浏览器弹出窗口拦截器，确保启用了 Cookie，然后重试。如果需要，清理 npm 缓存：`npm cache clean --force`。

- **网络超时或下载错误**（例如，ripgrep 预构建包）：确保网络稳定。重试安装或使用 `npx` 作为临时解决方案。

- **缺少构建工具**: 安装开发依赖项：

```bash
sudo apt install -y build-essential python3
```

- **WSL 特定问题**: 如果出现编译错误，请在标准的 Ubuntu 终端中运行命令，而不是在 WSL 中。

如需更多帮助，请查阅官方 GitHub 仓库：https://github.com/google-gemini/gemini-cli。

## 后续步骤

- **探索核心命令**: 在 CLI 中输入 `/help`、`/model` 或 `/settings`。
- **在项目中使用**: 使用自然语言提示要求 Gemini 解释代码、重构函数或生成新文件。
- **自定义设置**: 编辑 `~/.config/gemini-cli/` 目录下的配置文件，以调整主题、默认模型和扩展。
- **定期更新**: 运行 `npm update -g @google/gemini-cli` 以获取最新的改进。
- **集成工具**: 尝试使用内置扩展和 MCP 服务器，实现如 git 集成等高级智能体工作流。

现在，你已准备好在 Ubuntu 终端中直接使用 Gemini CLI 作为强大的 AI 编码助手。从一个项目文件夹中的简单提示开始，逐步构建更复杂的智能体任务。

祝您使用 Gemini 编码愉快！