安裝 Gemini CLI

你是 Gemini CLI 安裝顧問。

【角色】
Gemini CLI 安裝顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟。

【輸入】
- 作業系統：___
- 是否有 Node / 包管理器等依賴：___
- 是否需要鎖版本：___
- 遇到的安裝問題：___

【工作流程】
1. 確認依賴是否就緒
2. 給對應系統的安裝步驟
3. 驗證安裝成功
4. 說明更新 / 鎖版本

【輸出規範】
▌一、依賴檢查
▌二、安裝步驟
▌三、驗證可用
▌四、更新 / 鎖版本

【硬約束】
- 按我的系統給步驟
- 全域安裝注意許可權
- 依賴缺失先補再裝
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述
- 給的安裝步驟要讓我能照著一步步做下去，不跳過依賴檢查或假設我已裝好某個前提工具

Gemini CLI 安裝不應該從"把所有命令都試一遍"開始。先選一個與你的使用場景匹配的入口：長期本機使用裝 npm 或 Homebrew，只試一次用 npx，隔離執行用 sandbox，開發 Gemini CLI 本身才從原始碼跑。

1. 先選安裝路徑

flowchart TD
    Start["準備安裝"] --> LongTerm{"長期本機使用?"}
    LongTerm -->|是| Npm["npm global 或 Homebrew"]
    LongTerm -->|否| Try{"只是臨時試用?"}
    Try -->|是| Npx["npx @google/gemini-cli"]
    Try -->|否| Isolate{"需要隔離工具執行?"}
    Isolate -->|是| Sandbox["Docker / Podman sandbox"]
    Isolate -->|否| Source{"要開發 Gemini CLI 本身?"}
    Source -->|是| Dev["原始碼執行"]
    Source -->|否| Npm

    style Npm fill:#dcfce7,stroke:#22c55e
    style Sandbox fill:#fef3c7,stroke:#f59e0b
    style Dev fill:#fee2e2,stroke:#ef4444

2. 官方推薦環境

按官方 installation.mdx 目前列出的具體要求：

3. npm 全域安裝

npm install -g @google/gemini-cli
gemini

這是官方 get started 和 deployment 文件裡的標準路徑。適合日常本機使用。

安裝後先驗證命令是否真的在 PATH 裡：

gemini --version
which gemini

如果 gemini 找不到，優先查 npm global bin 路徑、shell PATH 和 Node 版本，不要馬上切到另一種安裝方式。

4. npx 臨時執行

npx @google/gemini-cli

適合第一次試用或不想全域安裝。缺點是每次啟動的可控性和速度不如固定安裝。

官方首頁也給了從 GitHub 直接執行最新程式碼的方式：

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

這個入口適合測試最新主分支，不適合作為團隊預設安裝方式。團隊教學應該優先寫穩定 npm 或 Homebrew 路徑。

5. Homebrew

brew install gemini-cli
gemini

macOS / Linux 使用者如果習慣用 Homebrew 管 CLI，可以選這個。

MacPorts 備選（同樣靠系統包管理）：

sudo port install gemini-cli

Anaconda 備選（適合受限環境，把 Node 裝在 conda 環境裡）：

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

6. Docker / Podman sandbox

官方安裝頁提供兩種 sandbox 思路（具體映象版本號請以 官方 installation 頁 目前版本為準）：

docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1

或者本機已安裝 CLI 後：

gemini --sandbox -y -p "your prompt here"

7. 原始碼執行

如果你要參與 Gemini CLI 本身開發，才需要從原始碼執行：

npm run start
npm link packages/cli
gemini

普通使用者不需要走原始碼路徑。原始碼執行會引入儲存庫依賴、構建狀態、分支變化和本地 link 問題；這不是學習 Gemini CLI 的必要成本。

8. 安裝後驗收

安裝驗收只看四件事：

1. gemini --version 能輸出版本。
2. gemini 能啟動互動式介面。
3. 目前 shell 能找到同一個 gemini 路徑。
4. 你知道自己下一步要用哪種認證方式。

不要在認證之前進入真實儲存庫大改。安裝只是把 CLI 放到機器上，真正決定能不能用的是賬號、專案、許可權、quota、隱私和工具確認策略。

9. 接下來去哪

官方來源

• Gemini CLI Get Started
• Gemini CLI Execution and Deployment
• Gemini CLI GitHub