发布通道

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。