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

前置条件

在 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：更新系统软件包

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

sudo apt update && sudo apt upgrade -y

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

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

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

推荐方法：NodeSource 仓库

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

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

为了方便版本管理：

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

验证安装：

node --version
npm --version

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

步骤 3：安装 Gemini CLI

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

npm install -g @google/gemini-cli

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

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

如果您想先试用一下：

npx @google/gemini-cli

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

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

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 是否正确安装：

gemini --version

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

步骤 5：启动并验证身份

首次运行 CLI：

gemini

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

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

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

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 作为临时解决方案。

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

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 编码愉快！