Gemini CLI 执行与部署

本文档介绍如何运行 Gemini CLI，并解释 Gemini CLI 使用的部署架构。

运行 Gemini CLI

有多种方式可以运行 Gemini CLI。选择哪种方式取决于您打算如何使用 Gemini CLI。

1. 标准安装（推荐给典型用户）

这是终端用户安装 Gemini CLI 的推荐方式。它涉及从 NPM 注册表下载 Gemini CLI 包。

全局安装：

# 全局安装 CLI
npm install -g @google/gemini-cli

# 现在您可以在任何地方运行 CLI
gemini

NPX 执行：

# 无需全局安装即可从 NPM 执行最新版本
npx @google/gemini-cli

2. 在沙箱中运行 (Docker/Podman)

出于安全和隔离考虑，Gemini CLI 可以在容器内运行。这是 CLI 执行可能产生副作用的工具时的默认方式。

直接从注册表运行： 您可以直接运行已发布的沙箱镜像。这在您只安装了 Docker 但仍想运行 CLI 的环境中非常有用。
```
# 运行已发布的沙箱镜像
docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1
```
使用 --sandbox 标志： 如果您已在本地安装 Gemini CLI（使用上述标准安装方法），可以指示它在沙箱容器内运行。
```
gemini --sandbox "您的提示内容"
```

3. 从源代码运行（推荐给 Gemini CLI 贡献者）

项目贡献者会希望直接从源代码运行 CLI。

开发模式： 此方法提供热重载功能，适用于活跃开发阶段。
```
# 在仓库根目录下
npm run start
```

类生产模式（链接包）： 此方法通过链接本地包来模拟全局安装。适用于在生产工作流中测试本地构建。

# 将本地 cli 包链接到全局 node_modules
npm link packages/cli

# 现在可以使用 `gemini` 命令运行您的本地版本
gemini

4. 从 GitHub 运行最新的 Gemini CLI 提交

您可以直接从 GitHub 仓库运行最近提交的 Gemini CLI 版本。这对于测试仍在开发中的功能非常有用。

# 直接从 GitHub 主分支执行 CLI
npx https://github.com/google-gemini/gemini-cli

部署架构

上述执行方式由以下架构组件和流程实现：

NPM 包

Gemini CLI 项目是一个 monorepo，向 NPM 注册表发布两个核心包：

@google/gemini-cli-core：后端，处理逻辑和工具执行
@google/gemini-cli：面向用户的前端

这些包在标准安装和从源代码运行 Gemini CLI 时使用。

构建与打包流程

根据分发渠道不同，采用两种不同的构建流程：

NPM 发布：对于发布到 NPM 注册表的情况，@google/gemini-cli-core 和 @google/gemini-cli 中的 TypeScript 源代码会使用 TypeScript 编译器 (tsc) 转译为标准 JavaScript。生成的 dist/ 目录就是发布到 NPM 包中的内容。这是 TypeScript 库的标准做法。
GitHub npx 执行：当直接从 GitHub 运行最新版 Gemini CLI 时，package.json 中的 prepare 脚本会触发不同的流程。该脚本使用 esbuild 将整个应用及其依赖项打包成一个自包含的 JavaScript 文件。这个打包文件是在用户机器上即时生成的，不会提交到代码库中。

Docker 沙盒镜像

基于 Docker 的执行方式由 gemini-cli-sandbox 容器镜像支持。该镜像发布到容器注册表，包含预安装的全局版 Gemini CLI。scripts/prepare-cli-packagejson.js 脚本在发布前会动态地将该镜像的 URI 注入到 CLI 的 package.json 中，这样当使用 --sandbox 标志时，CLI 就知道要拉取哪个镜像。

发布流程

统一的脚本 npm run publish:release 负责协调整个发布流程。该脚本执行以下操作：

使用 tsc 构建 NPM 包
更新 CLI 的 package.json 文件中的 Docker 镜像 URI
构建并标记 gemini-cli-sandbox Docker 镜像
将 Docker 镜像推送到容器注册表
将 NPM 包发布到制品注册表