---
title: "本地开发"
description: "Gemini CLI 本地开发入口：源码安装、monorepo package、NPM workspace、build/test 与发布相关概念。"
verifiedAt: "2026-05-09"
---

如果你要贡献 Gemini CLI 或排查 CLI 自身问题，需要理解它的 monorepo 结构，而不是只会 `npm install -g`。

> [!IMPORTANT]
> 本地开发不是普通用户的安装方式。教程正文应把“使用 Gemini CLI”和“开发 Gemini CLI 源码”分开，避免读者把源码构建当成日常排错步骤。

## 适用人群

| 你是谁 | 推荐路径 | 不建议做什么 |
| --- | --- | --- |
| 普通 CLI 用户 | 用 stable channel、读 troubleshooting 和 release notes | 为了解决登录、配额或 shell 问题直接 clone 源码 |
| 插件 / 自动化作者 | 用 headless、hooks、MCP、GitHub Action 验证集成 | 修改 CLI 源码绕过产品边界 |
| 官方贡献者 | clone 仓库、跑 build/test/preflight、按贡献流程提交 PR | 只跑 `npm install` 就认为环境可用 |
| CLI 自身 bug 排查 | 最小复现、源码构建、telemetry traces、issue 证据 | 把业务项目问题混进 CLI bug 报告 |

## 主要包

```text
@google/gemini-cli       用户入口、命令解析、终端 UI、可执行包
@google/gemini-cli-core  API 请求、认证、缓存、核心逻辑
```

`@google/gemini-cli` 发布时会被打成一个自包含可执行文件。普通用户全局安装或 `npx` 运行时，用到的是这个入口。

## Workspace

官方仓库使用 NPM Workspaces 管理 `packages/*`。

```json
{
  "workspaces": ["packages/*"]
}
```

这意味着在仓库根目录安装依赖时，workspace 内包会被统一安装和链接。

```mermaid
flowchart LR
    Repo["gemini-cli repo"] --> Workspaces["NPM workspaces"]
    Workspaces --> Cli["@google/gemini-cli"]
    Workspaces --> Core["@google/gemini-cli-core"]
    Cli --> Bundle["self-contained executable"]
    Core --> Runtime["auth / API / cache / tools"]
    Bundle --> User["npx / global install"]

    style Repo fill:#dbeafe,stroke:#3b82f6
    style Cli fill:#dcfce7,stroke:#22c55e
    style Core fill:#fef3c7,stroke:#f59e0b
```

## 开发前检查

贡献或排障时，建议按顺序做：

```bash
npm install
npm run build
npm run test
npm run preflight
```

如果只是用户侧使用，不需要从源码构建，直接使用 stable channel 更稳。只有当官方 issue、PR review 或最小复现明确需要源码验证时，才进入这条路径。

## 验证矩阵

| 检查项 | 通过标准 | 失败时先看 |
| --- | --- | --- |
| 依赖安装 | workspace 包能正常 linked | Node / NPM 版本、lockfile、网络代理 |
| Build | CLI 和 core 都能编译 | TypeScript error、package 边界、ESM 导入 |
| Test | 单元测试和相关集成测试通过 | 最近改动、fixture、平台差异 |
| Preflight | 官方提交前检查通过 | lint、format、typecheck、测试残留 |
| Telemetry | 能看到 model/tool 事件 | collector、端口、trace target、日志目录 |

## 发布渠道

官方发布分 stable、preview、nightly。普通用户用 stable，想提前测试新功能再考虑 preview，只有能接受回归风险时才用 nightly。

## 调试 telemetry

本地开发可以打开 OpenTelemetry traces，观察 model calls、tool scheduler 和 tool calls。官方本地开发文档提供三种查看方式：Genkit Developer UI、Jaeger、Google Cloud Trace。

本地排查优先用 local / Jaeger，不要一上来把开发 traces 发到 Google Cloud。需要 GCP 时，先确认 project、认证、IAM 和 API 都准备好。

常见本地启动方式：

```bash
npm run telemetry -- --target=local
```

然后另开一个终端运行 `gemini`，到 Jaeger UI 查看 traces。collector 日志通常在 `~/.gemini/tmp/<projectHash>/otel/` 下。

## 贡献和排错边界

普通教程读者不需要源码构建；源码开发页应该明确只服务两类人：要给官方仓库贡献代码的人，以及要定位 Gemini CLI 自身 bug 的人。遇到使用问题，先升级 stable、看 release notes 和 troubleshooting；不要把源码构建作为普通故障排查第一步。

更稳的 issue 证据结构：

1. 说明 CLI 版本、发布渠道、认证方式和系统环境。
2. 提供最小复现命令，剔除业务项目里的私有文件。
3. 附上失败日志或 trace 摘要，不贴 token、prompt 全文和内部路径。
4. 说明 stable / preview / nightly 是否都复现。
5. 如果已经定位源码位置，再补 build/test/preflight 结果。

## 验收方式

源码开发环境至少跑过 build、test、preflight。Telemetry 调试则要确认 collector 启动、CLI 产生 trace、UI 能看到 model/tool 事件。只完成 `npm install` 不算本地开发环境可用。

## 下一步

<Cards>
  <Card title="故障排查与参考" description="普通使用问题先回到 troubleshooting，不把源码构建当第一步。" href="/docs/gemini-cli/official/08-troubleshooting-reference" />
  <Card title="Headless mode" description="需要脚本调用 Gemini CLI 时，优先用 headless，而不是改源码。" href="/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="Telemetry" description="需要 traces、metrics、logs 时，先看 telemetry 的数据边界。" href="/docs/gemini-cli/official/06-security-enterprise/64-telemetry" />
</Cards>

## 官方来源

- [Gemini CLI local development](https://github.com/google-gemini/gemini-cli/blob/main/docs/local-development.md)
- [Gemini CLI package overview](https://github.com/google-gemini/gemini-cli/blob/main/docs/npm.md)
