---
title: "Release notes"
description: "Gemini CLI release notes：stable、preview、nightly 三个渠道，以及如何根据风险选择版本。"
verifiedAt: "2026-05-09"
---

Gemini CLI 更新很快。看 release notes 的目的不是追新，而是判断你当前教程、工作流和脚本有没有被版本变化影响。

> [!IMPORTANT]
> 教程、自动化脚本和 CI 不应默认跟 nightly。除非文章明确写“实验能力”，否则以 stable 为基准，并记录验证日期。

## 三个渠道

```text
stable   推荐给普通用户和生产工作流
preview  给愿意提前反馈新功能的用户
nightly  每日构建，风险最高
```

安装命令：

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

## 官方发布节奏

官方 release 文档描述了 stable、preview、nightly 的晋级流程。大体上，main 分支的新变化先进入 nightly，再进入 preview，最后晋级 stable。

官方文档还描述了每周发布节奏：新的 stable 和 preview 通常按周发布，nightly 每天从 main 发布。稳定发布会经过 promotion；patch 会针对 stable / preview 按需修复。

## 渠道选择表

| 使用场景 | 推荐渠道 | 需要记录 |
| --- | --- | --- |
| 新手教程、公开课程、团队 SOP | stable / `latest` | CLI 版本、验证日期、认证方式 |
| 预览即将上线的能力 | preview | 具体版本、回退方式、差异说明 |
| 复现 main 分支新 bug 或新功能 | nightly | 安装时间、npm 版本、是否可回 stable |
| CI / GitHub Action | stable，必要时 pin 版本 | workflow 输入、权限、失败日志 |
| 截图教程 | stable + 固定验证日期 | UI 是否随版本变化 |

## 看 release notes 的顺序

1. 先看当前安装版本：`gemini --version`。
2. 再看 npm dist-tag：`latest`、`preview`、`nightly`。
3. 对比 changelog latest 和 preview。
4. 如果教程依赖实验功能，记录具体版本和验证日期。
5. 如果自动化脚本失败，先查是否有 CLI 参数、输出格式、approval mode 或工具名变更。

NPM dist-tag 是版本渠道判断的关键来源。遇到“我明明装了 preview/nightly，但行为像 stable”的情况，先查 npm 当前 tag、`command -v gemini` 和安装来源，再判断是不是 PATH 或包管理器混用。

## 教程维护建议

Gemini CLI 栏目要定期检查这些变化：

- 新命令。
- 配置字段变更。
- 模型默认值变更。
- sandbox 和权限策略变化。
- hooks、skills、subagents 这类 agent 能力变化。
- GitHub Action 输入、权限和 secret 变化。

推荐把 release 复检拆成三类：

| 变化类型 | 需要检查的页面 |
| --- | --- |
| 新命令 / 参数 | CLI reference、commands、quickstart |
| 权限 / sandbox / policy | security、tools、automation |
| 模型 / quota / 认证 | authentication、quota、models、privacy |
| GitHub Action | automation、issue / PR automation |
| 包结构 / 安装 | installation、uninstall、npm package |

## 不建议

不要把 nightly 行为写成稳定教程。可以写“实验能力”，但要标清版本和验证日期。

## 验收方式

教程更新前用 stable 复跑核心路径，再用 preview 检查即将变化的 UI 和命令。只要发现命令、配置字段、默认模型、权限提示发生变化，就把对应页面标记为需复核，而不是只改一处截图。

## 下一步

<Cards>
  <Card title="NPM package" description="版本和发布问题继续看 package 结构和 workspace 边界。" href="/docs/gemini-cli/official/08-troubleshooting-reference/84-npm-package" />
  <Card title="Release channels" description="普通读者如何选择 stable / preview / nightly，回看发布渠道页。" href="/docs/gemini-cli/official/00-getting-started/05-release-channels" />
  <Card title="GitHub Action" description="CI 自动化受版本影响时，回看 GitHub Action 配置。" href="/docs/gemini-cli/official/07-integrations-automation/74-github-action" />
</Cards>

## 官方来源

- [Gemini CLI releases](https://github.com/google-gemini/gemini-cli/blob/main/docs/releases.md)
- [Gemini CLI releases documentation](https://google-gemini.github.io/gemini-cli/docs/releases.html)
- [Gemini CLI changelog latest](https://github.com/google-gemini/gemini-cli/blob/main/docs/changelogs/latest.md)
- [Gemini CLI changelog preview](https://github.com/google-gemini/gemini-cli/blob/main/docs/changelogs/preview.md)
