Gemini CLI 运行与部署

本文介绍如何运行 Gemini CLI 以及相关的部署架构。

运行方式

可按需求选择不同方式：

• 标准安装：最直接的使用方式。
• 在沙箱中运行：提供更高的隔离与安全性。
• 从源码运行：适合贡献者或需要调试的场景。

1. 标准安装（推荐）

通过 NPM 安装发布包：

• 全局安装

  npm install -g @google/gemini-cli

  安装后可在任意位置执行：

  gemini

• 使用 npx

  npx @google/gemini-cli

  npx 会直接运行最新版本，无需提前安装。

2. 在沙箱中运行（Docker / Podman）

为提升安全性，可在容器环境中运行 CLI，这也是 CLI 默认执行具备副作用工具时采用的方式。

• 直接运行发布的沙箱镜像

  docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1

• 本地安装后，通过 --sandbox 切换

  gemini --sandbox -y -p "your prompt here"

3. 从源码运行（贡献者推荐）

• 开发模式（HMR）

  npm run start

  会在源码变动时自动重载。

• 模拟全局安装（npm link）

  npm link packages/cli
  gemini

  适合在本地构建后以接近生产的方式测试。

4. 运行 GitHub 最新提交

测试最新提交的功能可直接从仓库执行：

npx https://github.com/google-gemini/gemini-cli

部署架构概览

上述运行方式依赖以下组件：

• NPM 包：Monorepo 发布两个核心包：

  • @google/gemini-cli-core：后端与工具执行逻辑；
  • @google/gemini-cli：面向用户的前端。

• 构建与打包流程：

  • NPM 发布：使用 tsc 将 TypeScript 转译为 JavaScript，并发布 dist/ 目录。
  • GitHub npx：由 prepare 脚本启用 esbuild，在本地打包为单文件运行，无需提交到仓库。

• Docker 沙箱镜像：gemini-cli-sandbox 镜像来自官方容器仓库，内置了全局安装的 CLI。

发布流程

Github Actions 自动化流程包含：

1. 使用 tsc 构建 NPM 包；
2. 将包发布至 artifact registry；
3. 创建 GitHub Release 并附带打包后的资产。