---
title: "安装、认证和第一次启动"
description: "Gemini CLI 起步流程：安装方式、认证选择、第一次运行和低风险只读任务。"
verifiedAt: "2026-05-09"
---

Gemini CLI 上手不要先追复杂配置。第一目标是：**确认本机能启动、认证能通过、能在一个项目里完成低风险只读任务**。

> [!IMPORTANT]
> 第一次启动的目标不是证明它“能改代码”，而是证明它能在你的环境里稳定读取上下文、遵守只读边界，并把下一步说清楚。

## 安装前检查

先用 `node --version` 和 `npm --version` 确认 Node 环境。

Gemini CLI 是 Node/npm 生态里的 CLI。官方常见入口包括 `npx`（临时运行 npm 包的命令）和全局安装。

起步时还要顺手看三件事：

| 检查项 | 为什么要看 |
| --- | --- |
| `node --version` | Node 过旧或来源混乱会导致 CLI 和依赖报错 |
| `npm config get prefix` | 全局安装后 `gemini` 是否能进 PATH |
| 当前网络 / 代理 | 登录、证书、npm 安装和 web 工具都会受影响 |

## 运行方式

临时运行（不写入全局 `node_modules`）：

```bash
npx @google/gemini-cli
```

全局安装（每次直接 `gemini` 启动）：

```bash
npm install -g @google/gemini-cli@latest
gemini
```

全局安装适合长期使用；`npx` 适合临时体验或确认环境。两者背后都是同一个官方包 `@google/gemini-cli`，按官方 [安装页](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/installation.mdx) 的当前推荐为准。

## 认证方式怎么选

常见认证入口有三类：

- **Google 登录**：适合个人体验 Gemini Code Assist 能力。免费层每天约 1000 次模型请求，Gemini CLI 自动选模型。
- **Gemini API Key**：适合脚本、第三方工具和轻量自动化（headless，无人值守环境）。**注意 Free 层每天 250 次且只能用 Flash 模型**——要用 Pro / Auto 必须切付费。
- **Vertex AI**：适合企业、云项目、统一账单和 IAM（Identity and Access Management，身份与访问管理）治理。Express 模式免费但 90 天后必须 enable billing。

如果只是第一次学习，先用官方默认登录流程即可。要进入 CI、GitHub Action 或第三方 agent 集成时，再使用 API key 或 Vertex AI。

| 使用场景 | 更适合的认证入口 |
| --- | --- |
| 本机交互体验 | Google 登录 |
| 简单脚本和 headless | Gemini API Key |
| 企业项目、统一账单、IAM | Vertex AI |
| GitHub Action | Secret / Workload Identity / 项目级认证策略 |

## 第一次启动

进入一个低风险目录：

可以新建 `gemini-cli-test` 目录，进入后运行 `gemini`。

第一次不要让它修改文件，先问只读问题：

第一次 prompt 可以是：`请只读分析当前目录，说明这里有哪些文件、你能看到什么、下一步建议我怎么组织项目。`

如果当前目录为空，可以让它生成一个计划，不要直接生成大量文件。

## 第一次启动后看什么

启动成功不等于配置完成。先检查这几个信号：

- 它是否能说清当前目录里有什么。
- 它是否遵守"只读、不修改"的要求。
- 它是否会主动说明需要哪些文件和验证命令。
- 它是否把认证、配额或网络问题直接暴露出来。
- 它是否把不确定的地方标出来，而不是硬猜。

> [!TIP]
> **跑通第一条只读任务后，立即用 `/init` 让 Gemini CLI 自动生成首份 `GEMINI.md`**。它会扫描项目结构、入口文件、检查命令，写一份初稿放在项目根目录。你只需要补"禁止触碰的文件 / 团队协作边界"等人类才知道的规则，比从零写更省事。详见 [GEMINI.md 篇](/docs/gemini-cli/understanding/04-project-context-gemini-md)。

## 在真实项目里第一条 prompt

进入真实项目后建议这样开始：

进入真实项目后的第一条 prompt 建议是：`请先只读扫描当前项目，不要修改文件，不要执行写入命令。请说明项目技术栈、入口文件、测试命令、构建命令和潜在风险。`

这个 prompt 的关键不是措辞，而是边界：只读、不修改、不执行写入命令、先产出判断。

## 常见起步问题

- `gemini` command not found：检查全局 npm bin 是否在 `PATH`。
- 登录失败：先看账号地区、组织 entitlement、`GOOGLE_CLOUD_PROJECT` 环境变量。
- 429：说明请求或配额触顶，先降低频率。
- CI 里不进交互模式：检查 `CI` 或 `CI_` 前缀环境变量。

## 第一次成功标准

第一次成功不是“能打开欢迎界面”，而是完成一条只读任务，并能看到当前目录、认证状态、模型或配额提示、下一步建议。建议把这次结果截图或记录下来，作为后续排障基线。

如果后续换了 Node、npm prefix、代理、账号或 Cloud project，先和这条基线对比。

## 认证基线

第一次启动后要知道自己用的是哪条认证链路。Google 登录、Gemini API Key、Vertex AI、Cloud Shell 和 GitHub Action secret 的排错路径不同。比如 API key 更适合 headless 和脚本，Vertex AI 更适合企业项目和 IAM，Google 登录更适合个人交互体验。

教程里不要把一种认证方式的 UI、配额和隐私边界写成所有读者都会看到的结果。每篇涉及认证的页面都要说明“以你的账号实际可见为准”。

## 官方资料

- 官方安装：[docs/get-started/installation.mdx](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/installation.mdx)
- 官方认证：[docs/get-started/authentication.mdx](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/authentication.mdx)
- Quickstart：[docs/get-started/index.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/index.md)
- 配额与定价：[docs/resources/quota-and-pricing.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/quota-and-pricing.md)

## 下一篇

<Cards>
  <Card title="Gemini CLI 怎么完成一个任务" description="跑通后，理解它的上下文、计划、工具调用和观察循环。" href="/docs/gemini-cli/understanding/03-how-gemini-cli-works" />
  <Card title="安装方式" description="需要查 npx、npm、Cloud Shell 和 release channel 时，回到官方安装页。" href="/docs/gemini-cli/official/00-getting-started/01-installation" />
  <Card title="认证方式" description="需要细分 OAuth、API key、Vertex AI 和 Cloud Shell 时，回到认证页。" href="/docs/gemini-cli/official/00-getting-started/02-authentication" />
</Cards>
