---
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="/docs/gemini-cli/understanding" />
  <Card title="本地开发" description="需要贡献 Gemini CLI 时，回看本地开发流程。" href="/docs/gemini-cli/official/07-integrations-automation/76-local-development" />
  <Card title="卸载" description="包冲突或旧缓存问题，回到卸载和清理页面。" href="/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)
