---
title: "发布通道"
description: "Gemini CLI stable、preview、nightly 三个发布通道的区别，以及普通用户、测试用户、贡献者应该怎么选。"
verifiedAt: "2026-05-09"
---

Gemini CLI 有 stable、preview、nightly 三类 npm 发布通道。普通用户默认选 stable；preview 用来提前试新功能；nightly 只适合测试、复现问题或贡献者验证。

> [!NOTE]
> **推荐**：真实项目、课程复现、团队默认环境都用 stable。不要为了“最新版”把 nightly 放进团队安装文档。

## 1. 选择总表

| 通道 | npm tag | 适合谁 | 风险 |
| --- | --- | --- | --- |
| stable | `latest` | 日常开发、课程、团队默认 | 最低 |
| preview | `preview` | 提前试新功能、能接受回归的用户 | 中等 |
| nightly | `nightly` | 测试者、贡献者、特定 bug 验证 | 最高 |

```mermaid
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 和验证组成。

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

适合：

- 真实项目。
- 课程学员。
- 团队默认环境。
- 不想频繁处理回归问题的用户。

## 3. preview

preview 每周发布，但官方明确提示没有完全验证，可能包含回归或未解决问题。

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

适合：

- 想提前试新功能。
- 能接受偶发回归。
- 愿意反馈问题。

preview 可以用于个人试用，但不应该无说明地写进团队 onboarding。如果团队要试 preview，要说明回滚方式和问题反馈入口。

## 4. nightly

nightly 每天发布，包含主分支在发布时的所有变化。官方文档提醒应假设它存在待验证问题。

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

适合：

- 测试者。
- 贡献者。
- 需要验证某个刚合并修复的人。

nightly 不适合作为教程默认命令。它的价值是缩短问题复现和修复验证周期，而不是提供稳定体验。

## 5. 团队怎么固定版本

团队教程不要只写“装最新版”。更稳的写法是：

- 默认使用 `@latest`。
- 在 onboarding 文档记录当前验证过的版本。
- 出现回归时，先记录 `gemini --version`、操作系统、Node 版本和认证方式。
- 升级前先在样板仓库跑只读任务、单文件写入和测试命令。
- 需要 preview / nightly 时，给出退出路径，改回 `@latest`。

> [!IMPORTANT]
> **版本问题不要和认证问题混在一起**：如果启动失败，先区分安装路径、Node 版本、认证方式、quota、网络代理和 CLI 版本。直接切 nightly 往往会把问题扩大。

## 6. 选择建议

| 需求 | 选择 |
| --- | --- |
| 稳定日常开发 | stable |
| 课程或教程复现 | stable |
| 新功能试用 | preview |
| bug 复现或贡献测试 | nightly |
| 团队统一环境 | 固定 stable，并记录版本 |

## 7. 更新方式

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

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

如果用 Homebrew，则按 Homebrew 自己的升级流程处理。团队文档里只保留一种默认更新方式，避免成员混用 npm、Homebrew、npx 和 nightly 导致排障困难。

## 8. 接下来去哪

<Cards>
  <Card title="配额与费用" description="继续看 quota、pricing、认证方式和隐私条款之间的关系。" href="/docs/gemini-cli/official/00-getting-started/06-quota-and-pricing" />
  <Card title="模型选择" description="不要把版本通道和模型选择混淆，模型选择单独处理。" href="/docs/gemini-cli/official/05-models-runtime/51-model-selection" />
  <Card title="排障" description="如果安装或认证失败，按症状分层排查，而不是直接换 nightly。" href="/docs/gemini-cli/official/08-troubleshooting-reference/81-troubleshooting" />
</Cards>

## 官方来源

- [Gemini CLI Homepage](https://google-gemini.github.io/gemini-cli/)
- [Gemini CLI Execution and Deployment](https://google-gemini.github.io/gemini-cli/docs/get-started/deployment.html)
- [Gemini CLI GitHub Releases](https://github.com/google-gemini/gemini-cli/releases)
