---
title: "NPM package"
description: "Gemini CLI NPM package 結構：@google/gemini-cli、@google/gemini-cli-core、workspace 與釋出包邊界。"
verifiedAt: "2026-05-09"
---

Gemini CLI 儲存庫是 monorepo。普通使用者只需要知道怎麼安裝；貢獻者和排障者需要知道包邊界。

> [!NOTE]
> 普通使用者安裝的是 CLI 入口，不需要直接依賴 core。只有原始碼貢獻、stack trace 排查或 package 釋出驗證時，才需要理解 workspace。

## 兩個核心包

`@google/gemini-cli` 是使用者入口，負責終端 UI、命令解析和執行檔；`@google/gemini-cli-core` 負責 Gemini API 請求、認證、本地快取和核心邏輯。

| 包 | 職責 | 面向誰 |
| --- | --- | --- |
| `@google/gemini-cli` | 終端 UI、命令解析、可執行入口、使用者側功能 | 普通使用者、教程讀者、CI |
| `@google/gemini-cli-core` | API 請求、認證、本地快取、核心邏輯 | 官方開發者、排障者、需要複用 core 的開發者 |

## 使用者安裝的是誰

普通使用者常見方式是 `npm install -g @google/gemini-cli` 或 `npx @google/gemini-cli`。

使用的是 `@google/gemini-cli` 這個自包含可執行入口。

## 為什麼要懂 core

當你遇到認證、快取、API 請求、模型呼叫、token 統計這類問題時，很多邏輯其實在 `@google/gemini-cli-core`。

`@google/gemini-cli-core` 不是普通使用者日常啟動入口。它更像可複用核心庫，包含與 Gemini API 互動、認證、本地快取等邏輯。排查 issue 時，看到 stack trace 進入 core，不代表安裝了兩個 CLI。

```mermaid
flowchart LR
    User["user runs gemini"] --> Cli["@google/gemini-cli"]
    Cli --> Bundle["bundled executable"]
    Bundle --> Core["@google/gemini-cli-core"]
    Core --> API["Gemini API / auth / cache"]
    Dev["source developer"] --> Workspace["NPM workspaces"]
    Workspace --> Cli
    Workspace --> Core

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

## Workspace 結構

官方儲存庫使用 NPM Workspaces：

根 `package.json` 中的 workspaces 指向 `packages/*`。

本地開發時，在根目錄安裝依賴即可讓 workspace 內包互相連結。

示例：

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

在 monorepo 根目錄執行 `npm install` 會安裝所有 workspace 依賴並自動連結內部包。要只跑某個包的指令碼，可以用 NPM workspace 引數，例如 `npm run build --workspace @google/gemini-cli`。

## 讀 stack trace

| trace 落點 | 可能含義 | 下一步 |
| --- | --- | --- |
| `packages/cli` | 終端 UI、命令解析、引數、互動流程 | 查 CLI command、flags、TUI 狀態 |
| `packages/core` | 認證、API、cache、tool scheduler | 查認證方式、模型呼叫、快取和工具執行 |
| `node_modules` | 依賴或環境問題 | 查 lockfile、Node 版本、包管理器 |
| `bundle` / executable | 釋出包或 npx 入口問題 | 查 release notes、npm tag、安裝來源 |

## 排錯判斷

- `gemini` 命令找不到：查全域性 npm bin、PATH、Homebrew/MacPorts 安裝路徑。
- `npx` 總是跑舊版本：清 `_npx` cache。
- 原始碼開發改動沒生效：確認 workspace link 和 build 產物。
- API、認證、cache 行為異常：優先看 core 相關 issue 和 logs。
- 使用者側教程失敗：先復現全域性安裝或 `npx`，不要直接從原始碼構建。

## 回到教程

官方教程中文版到這裡結束。下一步建議讀“從原理到實戰”，把這些官方能力串成真實專案工作流。

寫教程時的邊界：

- 安裝頁只講普通使用者入口，避免把 monorepo build 放進新手流程。
- 本地開發頁講 workspace、preflight、telemetry 和貢獻流程。
- 故障排查頁只在需要判斷原始碼問題時引入 package 邊界。
- 自動化頁預設呼叫釋出後的 CLI，而不是依賴本地原始碼路徑。

## 驗收方式

普通使用者用 `gemini --version` 驗證入口；原始碼貢獻者用根目錄 build/test/preflight 驗證 workspace。寫教程時，安裝頁只講 `@google/gemini-cli`，原始碼排障頁再解釋 core 和 workspace，避免新手混淆。

## 下一步

<Cards>
  <Card title="從原理到實戰" description="官方能力看完後，進入理解系列，把能力串成專案工作流。" href="/zh-Hant/docs/gemini-cli/understanding" />
  <Card title="本地開發" description="需要貢獻 Gemini CLI 時，回看本地開發流程。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/76-local-development" />
  <Card title="解除安裝" description="包衝突或舊快取問題，回到解除安裝和清理頁面。" href="/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/82-uninstall" />
</Cards>

## 官方來源

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