Gemini CLI 发布

发布节奏和标签

我们将尽可能严格遵循 https://semver.org/，但会在需要偏离时说明何时或是否必须偏离。我们的每周发布将是次版本增量，发布之间的任何错误或热修复将作为最新发布的补丁版本发布。

预览版

新的预览版将在每周二 UTC 23:59 发布。这些版本尚未经过完全审查，可能包含回归或其他未解决的问题。请帮助我们测试并使用 preview 标签安装。

bash

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

稳定版

新的稳定版将在每周二 UTC 20:00 发布，这将是上周发布的完整推广 + 任何错误修复和验证。使用 latest 标签。

bash

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

夜间版

新版本将在每天 UTC 00:00 发布，这将是发布时主分支的所有更改。应假设存在待定验证和问题。使用 nightly 标签。

bash

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

发布流程

其中 x.y.z 是要发布的下一个版本。在大多数情况下，对于每周发布，这将是 y 的增量，即次版本更新。主版本更新 x 需要更广泛的协调和沟通。对于补丁 z，请参见下文。在可能的情况下，我们将尽力遵守 https://semver.org/

我们的发布节奏是新版本先发送到预览通道一周，然后在一周后推广到稳定版。版本号将遵循 SemVer，每周发布增加次版本。对预览版和稳定版的补丁和错误修复将增加补丁版本。

夜间发布

每晚 UTC 00:00，我们将从 main 自动部署夜间发布。这将是下一个生产版本 x.y.z 的版本，带有夜间标签。

创建预览版发布

每周二 UTC 23:59，我们将自动部署下一个生产版本 x.y.z 的预览版发布。

这将作为"release"操作的计划实例发生。它将从 Main 分支切出。
这将创建一个分支 release/vx.y.z-preview.n
我们将对此分支和 npm 包运行评估和冒烟测试。目前这应该是手动冒烟测试，我们没有专用的矩阵或特定的详细流程。即将有工作使这更加正式化和自动化，请参见 https://github.com/google-gemini/gemini-cli/issues/3788
安装 @preview 的用户也将获得此发布

推广稳定版发布

一周后（在下一个周二），在所有信号都正常的情况下，我们将在 UTC 20:00 通过当前值班人员手动发布。

发布操作将使用源分支 release/vx.y.z-preview.n
版本将是 x.y.z
发布者将创建并合并一个包含版本更改的 PR 到 main
将运行冒烟测试和手动验证。目前这应该是手动冒烟测试，我们没有专用的矩阵或特定的详细流程。即将有工作使这更加正式化和自动化，请参见 https://github.com/google-gemini/gemini-cli/issues/3788

补丁发布

如果需要在下一个计划发布之前修复关键错误，请按照此流程创建补丁。

1. 创建热修复分支

首先，为您的修复创建一个新分支。此分支的源取决于您是在修补稳定版还是预览版发布。

对于稳定版发布补丁： 从您需要修补的版本的 Git 标签创建分支。标签名称格式为 vx.y.z。
bash
```
# 示例：为 v0.2.0 创建热修复分支
git checkout v0.2.0 -b hotfix/issue-123-fix-for-v0.2.0
```

对于预览版发布补丁： 从现有的预览版发布分支创建分支，格式为 release/vx.y.z-preview.n。

bash

# 示例：为预览版发布创建热修复分支
git checkout release/v0.2.0-preview.0 && git checkout -b hotfix/issue-456-fix-for-preview

2. 实施修复

在您的新热修复分支中，要么创建一个包含修复的新提交，要么从 main 分支中挑选现有提交。将您的更改合并到热修复分支的源中（例如 https://github.com/google-gemini/gemini-cli/pull/6850）。

3. 执行发布

使用"Release" GitHub Actions 工作流程遵循手动发布流程。

版本：对于稳定版补丁，增加补丁版本（例如，v0.2.0 -> v0.2.1）。对于预览版补丁，增加预览版号（例如，v0.2.0-preview.0 -> v0.2.0-preview.1）。
Ref：使用您的源分支作为参考（例如 release/v0.2.0-preview.0）

如何运行发布

4. 更新版本

热修复发布后，将更改合并回适当的分支。

对于稳定版发布热修复： 打开一个 pull request 将发布分支（例如，release/0.2.1）合并回 main。这保持 main 中的版本号是最新的。
对于预览版发布热修复： 打开一个 pull request 将新的预览版发布分支（例如，release/v0.2.0-preview.1）合并回现有的预览版发布分支（release/v0.2.0-preview.0）（例如 https://github.com/google-gemini/gemini-cli/pull/6868）

发布计划

日期	稳定版 UTC 20:00	预览版 UTC 23:59
2025年8月19日	N/A	0.2.0-preview.0
2025年8月26日	0.2.0	0.3.0-preview.0
2025年9月2日	0.3.0	0.4.0-preview.0
2025年9月9日	0.4.0	0.5.0-preview.0
2025年9月16日	0.5.0	0.6.0-preview.0
2025年9月23日	0.6.0	0.7.0-preview.0

如何发布

发布通过 release.yml GitHub Actions 工作流程管理。要为补丁或热修复执行手动发布：

导航到仓库的 Actions 选项卡。
从列表中选择 Release 工作流程。
点击 Run workflow 下拉按钮。
填写所需输入：
- Version：要发布的确切版本（例如，v0.2.1）。
- Ref：要发布的分支或提交 SHA（默认为 main）。
- Dry Run：保持为 true 以测试工作流程而不发布，或设置为 false 以执行实际发布。
点击 Run workflow。

TLDR

每个发布，无论是自动的还是手动的，都执行以下步骤：

从 main 分支检出最新代码。
安装所有依赖项。
运行完整的 preflight 检查和集成测试套件。
如果所有测试成功，它根据输入计算下一个版本号。
它创建一个名为 release/${VERSION} 的分支。
它创建一个名为 v${VERSION} 的标签。
然后它构建并使用提供的版本号将包发布到 npm。
最后，它为该版本创建一个 GitHub 发布。

故障处理

如果工作流程中的任何步骤失败，它将自动在仓库中创建一个带有 bug 和 release-failure 标签的新问题。该问题将包含指向失败工作流程运行的链接，以便于调试。

Docker

我们还运行一个名为 release-docker.yml 的 Google cloud build。它发布沙盒 docker 以匹配您的发布。一旦服务账户权限解决，这也将移至 GH 并与主发布文件合并。

发布验证

推送新发布后，应执行冒烟测试以确保包按预期工作。这可以通过本地安装包并运行一组测试来确保它们正常运行来完成。

npx -y @google/gemini-cli@latest --version 验证推送按预期工作，如果您没有使用 rc 或 dev 标签
npx -y @google/gemini-cli@<release tag> --version 验证标签适当推送
这在本地是破坏性的 npm uninstall @google/gemini-cli && npm uninstall -g @google/gemini-cli && npm cache clean --force && npm install @google/gemini-cli@<version>
建议进行基本的冒烟测试，运行一些 llm 命令和工具，以确保包按预期工作。我们将在未来更多地编码化这一点。

本地测试和验证：打包和发布流程的更改

如果您需要测试发布流程而不实际发布到 NPM 或创建公共 GitHub 发布，您可以从 GitHub UI 手动触发工作流程。

转到仓库的 Actions 选项卡。
点击"Run workflow"下拉菜单。
保持 dry_run 选项选中（true）。
点击"Run workflow"按钮。

这将运行整个发布流程，但会跳过 npm publish 和 gh release create 步骤。您可以检查工作流程日志以确保一切按预期工作。

在提交更改之前，在本地测试对打包和发布流程的任何更改是至关重要的。这确保包将正确发布，并且在用户安装时将按预期工作。

要验证您的更改，您可以执行发布流程的试运行。这将模拟发布流程而不实际将包发布到 npm 注册表。

bash

npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run

此命令将执行以下操作：

构建所有包。
运行所有预发布脚本。
创建将发布到 npm 的包 tarball。
打印将发布的包的摘要。

然后您可以检查生成的 tarball 以确保它们包含正确的文件，并且 package.json 文件已正确更新。tarball 将在每个包目录的根目录中创建（例如，packages/cli/google-gemini-cli-0.1.6.tgz）。

通过执行试运行，您可以确信您对打包流程的更改是正确的，包将成功发布。

发布深度解析

发布流程的主要目标是从 packages/ 目录获取源代码，构建它，并在项目根目录的临时 bundle 目录中组装一个干净、自包含的包。这个 bundle 目录是实际发布到 NPM 的内容。

以下是关键阶段：

阶段 1：发布前健全性检查和版本控制

发生什么：在移动任何文件之前，流程确保项目处于良好状态。这涉及运行测试、代码检查和类型检查（npm run preflight）。根 package.json 和 packages/cli/package.json 中的版本号更新为新的发布版本。
为什么：这保证只有高质量、可工作的代码被发布。版本控制是表示新发布的第一步。

阶段 2：构建源代码

发生什么：packages/core/src 和 packages/cli/src 中的 TypeScript 源代码被编译为 JavaScript。
文件移动：
- packages/core/src/*/.ts -> 编译为 -> packages/core/dist/
- packages/cli/src/*/.ts -> 编译为 -> packages/cli/dist/
为什么：开发期间编写的 TypeScript 代码需要转换为可以由 Node.js 运行的纯 JavaScript。核心包首先构建，因为 cli 包依赖于它。

阶段 3：组装最终可发布包

这是最关键的阶段，文件被移动和转换为发布的最终状态。在项目根目录创建一个临时的 bundle 文件夹来容纳最终的包内容。

package.json 被转换：
- 发生什么：从 packages/cli/ 读取 package.json，修改并写入根 bundle/ 目录。
- 文件移动：packages/cli/package.json -> （内存转换）-> bundle/package.json
- 为什么：最终的 package.json 必须与开发中使用的不同。关键更改包括：
  - 删除 devDependencies。
  - 删除工作区特定的 "dependencies": { "@gemini-cli/core": "workspace:*" } 并确保核心代码直接捆绑到最终的 JavaScript 文件中。
  - 确保 bin、main 和 files 字段指向最终包结构中的正确位置。
创建 JavaScript 捆绑包：
- 发生什么：来自 packages/core/dist 和 packages/cli/dist 的构建 JavaScript 被捆绑到单个可执行的 JavaScript 文件中。
- 文件移动：packages/cli/dist/index.js + packages/core/dist/index.js -> （由 esbuild 捆绑）-> bundle/gemini.js（或类似名称）。
- 为什么：这创建了一个包含所有必要应用程序代码的单个优化文件。它通过消除核心包成为 NPM 上单独依赖项的需要来简化包，因为其代码现在直接包含在内。
复制静态和支持文件：
- 发生什么：不是源代码一部分但包正确工作或良好描述所需的基本文件被复制到 bundle 目录中。
- 文件移动：
  - README.md -> bundle/README.md
  - LICENSE -> bundle/LICENSE
  - packages/cli/src/utils/*.sb（沙盒配置文件）-> bundle/
- 为什么：
  - README.md 和 LICENSE 是任何 NPM 包都应包含的标准文件。
  - 沙盒配置文件（.sb 文件）是 CLI 沙盒功能正常运行所需的关键运行时资产。它们必须位于最终可执行文件旁边。

阶段 4：发布到 NPM

发生什么：从根 bundle 目录内运行 npm publish 命令。
为什么：通过从 bundle 目录内运行 npm publish，只有我们在阶段 3 中仔细组装的文件被上传到 NPM 注册表。这防止任何源代码、测试文件或开发配置被意外发布，为用户提供干净和最小的包。

文件流摘要

mermaid

graph TD
    subgraph "源文件"
        A["packages/core/src/*.ts<br/>packages/cli/src/*.ts"]
        B["packages/cli/package.json"]
        C["README.md<br/>LICENSE<br/>packages/cli/src/utils/*.sb"]
    end

    subgraph "流程"
        D(构建)
        E(转换)
        F(组装)
        G(发布)
    end

    subgraph "产物"
        H["捆绑的 JS"]
        I["最终 package.json"]
        J["bundle/"]
    end

    subgraph "目标"
        K["NPM 注册表"]
    end

    A --> D --> H
    B --> E --> I
    C --> F
    H --> F
    I --> F
    F --> J
    J --> G --> K

此流程确保最终发布的产物是项目的专用构建、干净和高效的表示，而不是开发工作区的直接副本。

Gemini CLI 发布 ​

发布节奏和标签 ​

预览版 ​

稳定版 ​

夜间版 ​

发布流程 ​

夜间发布 ​

创建预览版发布 ​

推广稳定版发布 ​

补丁发布 ​

1. 创建热修复分支 ​

2. 实施修复 ​

3. 执行发布 ​

4. 更新版本 ​

发布计划 ​

如何发布 ​

TLDR ​

故障处理 ​

Docker ​

发布验证 ​

本地测试和验证：打包和发布流程的更改 ​

发布深度解析 ​

Gemini CLI 发布

发布节奏和标签

预览版

稳定版

夜间版

发布流程

夜间发布

创建预览版发布

推广稳定版发布

补丁发布

1. 创建热修复分支

2. 实施修复

3. 执行发布

4. 更新版本

发布计划

如何发布

TLDR

故障处理

Docker

发布验证

本地测试和验证：打包和发布流程的更改

发布深度解析