---
title: "Quickstart"
description: "Gemini CLI 第一次使用流程：安裝、認證、啟動、只讀解釋專案、處理檔案、執行測試和檢視配額。"
verifiedAt: "2026-05-09"
---

第一次使用 Gemini CLI，不要直接讓它重構專案。官方 quickstart 會帶你安裝、認證、配置和發起提示詞；真實專案裡更穩的順序是：先只讀理解，再讓它提出計劃，再限定一個檔案寫入，最後用測試或 diff 驗收。

> [!IMPORTANT]
> **第一次任務只讀**：先讓 Gemini CLI 解釋專案結構。確認它能讀對目錄、理解對目標、說清不確定性，再給寫許可權。

## 1. 最小啟動流程

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

啟動後完成認證，然後進入一個低風險 Git 儲存庫或練習目錄。第一條提示詞不要要求改檔案：

```text
请只读分析这个项目，不要修改任何文件。
输出：
1. 主要目录和入口文件。
2. 你会优先阅读的 5 个文件。
3. 这个项目最可能的测试命令。
4. 你现在还不确定的问题。
```

這條提示詞同時驗證三件事：Gemini CLI 能不能看到專案、能不能區分事實和推測、能不能遵守“不要修改檔案”。

## 2. 第一條安全閉環

```mermaid
flowchart TD
    A["啟動 gemini"] --> B["只讀解釋專案結構"]
    B --> C["指定一個小檔案讓它解釋"]
    C --> D["讓它提出修改計劃"]
    D --> E["確認後只改一個檔案"]
    E --> F["執行測試或檢查命令"]

    style B fill:#dcfce7,stroke:#22c55e
    style D fill:#fef3c7,stroke:#f59e0b
    style E fill:#fee2e2,stroke:#ef4444
```

第一條閉環合格，不是看回答有多長，而是看它有沒有做到：

- 沒有寫檔案。
- 能指出真實檔案和目錄。
- 能說出不確定的地方。
- 能給出下一步計劃，而不是直接動手。

## 3. 官方示例能說明什麼

官方示例覆蓋了幾類典型任務：

- 根據圖片內容重新命名照片。
- clone 並解釋一個遠端程式碼儲存庫。
- 合併兩個 CSV。
- 為登入頁面寫單元測試。

這些例子說明 Gemini CLI 不只會寫程式碼。它能結合檔案、命令、Web、模型能力做本地任務。但進入自己的專案時，要把範圍收小。

## 4. 第二輪才允許小範圍寫入

只讀任務跑通後，**先用 `/init` 讓 Gemini CLI 自動生成首份 `GEMINI.md`** ——它會掃描你的專案結構和檢查命令，寫一份初稿放在專案根目錄。這一步不算"修改原始碼"，只是給 AI 一份長期上下文規則檔案，後續你和 AI 溝通專案慣例就不用每次複述。

```text
/init
```

生成後開啟 `GEMINI.md` 檢查一遍，補三件人類才知道的規則：哪些檔案禁止觸碰、提交時跑哪些驗證命令、團隊協作邊界。詳見 [GEMINI.md 篇](/zh-Hant/docs/gemini-cli/official/02-context-config/21-gemini-md)。

然後再選一個低風險檔案做寫入，例如 README、測試說明、註釋或一個小 bug 的測試用例。

```text
只修改 README.md 的安装部分，把命令整理成 npm 和 Homebrew 两种路径。
不要修改其他文件。
改完后先解释 diff，再告诉我建议运行什么检查命令。
```

寫入後立刻檢查：

```bash
git diff --stat
git diff
```

如果 Gemini CLI 修改了未指定檔案，先停下來，不要繼續加新需求。回到提示詞、許可權、工作目錄和上下文邊界排查。

## 5. 第一次不要做什麼

- 不要讓它“最佳化整個專案”。
- 不要讓它直接處理金鑰、賬單、賬號、生產資料。
- 不要一開始就接 MCP 寫操作。
- 不要用 `--approval-mode=yolo` 處理真實專案。
- 不要在沒看 diff 的情況下接受大範圍修改。

> [!WARNING]
> **`--approval-mode=yolo` 不適合新手第一天**：它會降低人工確認門檻。真實專案先用可審查、可撤銷、範圍明確的任務證明 CLI 行為穩定，再考慮自動化。

## 6. 查用量

官方文件說明可以用：

```text
/stats model
```

檢視當前 session 的 token 用量、quota 資訊和模型相關限制。

不要把 `/stats model` 當成永久配額真相源。不同賬號、認證方式、Gemini Code Assist edition、API key、Vertex AI project 都可能影響可用額度。需要費用和 quota 決策時，回到官方 quota and pricing 頁面。

第一次成功跑通後，把安裝方式、認證方式和測試目錄記錄下來。後續教程截圖如果和讀者不同，最常見原因就是這三項不同。

## 7. 接下來去哪

<Cards>
  <Card title="Cloud Shell 入口" description="想免本機安裝或快速靠近 Google Cloud 專案，繼續看 Cloud Shell 邊界。" href="/zh-Hant/docs/gemini-cli/official/00-getting-started/04-cloud-shell" />
  <Card title="CLI 工作流" description="本機已經跑通後，進入 slash commands、shell、檔案、history 和 checkpoint。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow" />
  <Card title="工具總覽" description="準備讓 Gemini CLI 讀寫檔案、跑 shell 或接 MCP 前，先看工具許可權邊界。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/30-tools-overview" />
</Cards>

## 官方來源

- [Gemini CLI Get Started](https://google-gemini.github.io/gemini-cli/docs/get-started/)
- [Gemini CLI Examples](https://google-gemini.github.io/gemini-cli/docs/get-started/examples.html)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
