安裝 Gemini CLI

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