---
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 篇](/zh-Hant/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="/zh-Hant/docs/gemini-cli/understanding/03-how-gemini-cli-works" />
  <Card title="安裝方式" description="需要查 npx、npm、Cloud Shell 和 release channel 時，回到官方安裝頁。" href="/zh-Hant/docs/gemini-cli/official/00-getting-started/01-installation" />
  <Card title="認證方式" description="需要細分 OAuth、API key、Vertex AI 和 Cloud Shell 時，回到認證頁。" href="/zh-Hant/docs/gemini-cli/official/00-getting-started/02-authentication" />
</Cards>
