釋出通道

Gemini CLI 有 stable、preview、nightly 三類 npm 釋出通道。普通使用者預設選 stable；preview 用來提前試新功能；nightly 只適合測試、復現問題或貢獻者驗證。

推薦：真實專案、課程復現、團隊預設環境都用 stable。不要為了“最新版”把 nightly 放進團隊安裝文件。

1. 選擇總表

通道	npm tag	適合誰	風險
stable	`latest`	日常開發、課程、團隊預設	最低
preview	`preview`	提前試新功能、能接受迴歸的使用者	中等
nightly	`nightly`	測試者、貢獻者、特定 bug 驗證	最高

flowchart TD
    Need["需要安裝 Gemini CLI"] --> Real{"真實專案或課程復現?"}
    Real -->|是| Stable["stable / latest"]
    Real -->|否| Feature{"要提前試新功能?"}
    Feature -->|是| Preview["preview"]
    Feature -->|否| Contrib{"貢獻或復現剛合併的問題?"}
    Contrib -->|是| Nightly["nightly"]
    Contrib -->|否| Stable

    style Stable fill:#dcfce7,stroke:#22c55e
    style Preview fill:#fef3c7,stroke:#f59e0b
    style Nightly fill:#fee2e2,stroke:#ef4444

2. stable

stable 使用 latest tag。官方文件說明，新 stable release 每週釋出，由上一週 preview release 加 bug fix 和驗證組成。

npm install -g @google/gemini-cli
npm install -g @google/gemini-cli@latest

適合：

真實專案。
課程學員。
團隊預設環境。
不想頻繁處理迴歸問題的使用者。

3. preview

preview 每週釋出，但官方明確提示沒有完全驗證，可能包含迴歸或未解決問題。

npm install -g @google/gemini-cli@preview

適合：

想提前試新功能。
能接受偶發迴歸。
願意反饋問題。

preview 可以用於個人試用，但不應該無說明地寫進團隊 onboarding。如果團隊要試 preview，要說明回復方式和問題反饋入口。

4. nightly

nightly 每天釋出，包含主分支在釋出時的所有變化。官方文件提醒應假設它存在待驗證問題。

npm install -g @google/gemini-cli@nightly

適合：

測試者。
貢獻者。
需要驗證某個剛合併修復的人。

nightly 不適合作為教程預設命令。它的價值是縮短問題復現和修復驗證週期，而不是提供穩定體驗。

5. 團隊怎麼固定版本

團隊教程不要只寫“裝最新版”。更穩的寫法是：

預設使用 @latest。
在 onboarding 文件記錄當前驗證過的版本。
出現迴歸時，先記錄 gemini --version、作業系統、Node 版本和認證方式。
升級前先在樣板儲存庫跑只讀任務、單檔案寫入和測試命令。
需要 preview / nightly 時，給出退出路徑，改回 @latest。

版本問題不要和認證問題混在一起：如果啟動失敗，先區分安裝路徑、Node 版本、認證方式、quota、網路代理和 CLI 版本。直接切 nightly 往往會把問題擴大。

6. 選擇建議

需求	選擇
穩定日常開發	stable
課程或教程復現	stable
新功能試用	preview
bug 復現或貢獻測試	nightly
團隊統一環境	固定 stable，並記錄版本

7. 更新方式

按 npm tag 重灌是最直接、可解釋的更新方式：

npm install -g @google/gemini-cli@latest

如果用 Homebrew，則按 Homebrew 自己的升級流程處理。團隊文件裡只保留一種預設更新方式，避免成員混用 npm、Homebrew、npx 和 nightly 導致排障困難。

8. 接下來去哪

配額與費用

繼續看 quota、pricing、認證方式和隱私條款之間的關係。

模型選擇

不要把版本通道和模型選擇混淆，模型選擇單獨處理。

排障

如果安裝或認證失敗，按症狀分層排查，而不是直接換 nightly。