如何在 Ubuntu 上安裝 Gemini CLI：完整逐步教學

前置準備

在 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：更新系統套件

首先，更新您的套件清單並升級現有套件，以防止相依性衝突：

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 Version Manager)

若需更輕鬆的版本管理：

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

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

祝您使用 Gemini 愉快編碼！