# 如何在 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-TW

Language: zh-TW

Published: 2026-04-07

Updated: 2026-04-07

## 前置準備

在 Ubuntu 上開始安裝 Gemini CLI 之前，請準備好以下項目：

- **Ubuntu 版本**：20.04 LTS 或更新版本（22.04、24.04 和 26.04 完全支援）。
- **管理員權限**：用於套件管理的 Sudo 權限。
- **網路連線**：下載 Node.js、npm 套件和進行驗證所需。
- **Google 帳戶**：需要透過 OAuth 登入以存取 Gemini 模型。
- **建議硬體配置**：至少 4 GB RAM 和 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 Version Manager)

若需更輕鬆的版本管理：

```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 整合。

您現在已準備好使用 Gemini CLI，作為您 Ubuntu 終端機中強大的 AI 程式碼助理。請從專案資料夾中的簡單提示開始，逐步建構更複雜的代理任務。

祝您使用 Gemini 愉快編碼！