---
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="/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference" />
  <Card title="Headless mode" description="需要指令碼呼叫 Gemini CLI 時，優先用 headless，而不是改原始碼。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="Telemetry" description="需要 traces、metrics、logs 時，先看 telemetry 的資料邊界。" href="/zh-Hant/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)
