---
title: "檔案管理"
description: "Gemini CLI 檔案管理：@ 檔案引用、目錄上下文、查詢檔案、修改檔案、建立檔案、diff 確認和 .geminiignore。"
verifiedAt: "2026-05-09"
---

Gemini CLI 可以自己探索專案，也可以透過 `@` 顯式讀取你指定的檔案或目錄。檔案管理是它從“聊天”變成“agent”的關鍵能力，也是最容易越界的地方：讀錯檔案會誤判，改錯檔案會製造無關 diff。

> [!IMPORTANT]
> **先只讀，再修改**：第一次接入專案時，先讓它解釋檔案結構；確認讀對以後，再授權編輯。

## 1. 顯式讀取檔案

單檔案示例：`@src/components/UserProfile.tsx 解釋這個元件如何處理使用者資料。`

多個檔案可以一起給：

`@src/components/UserProfile.tsx @src/types/User.ts 檢查這兩個檔案的型別關係。`

目錄也可以給：

`@src/utils/ 檢查這些工具函式是否還有 deprecated API。`

顯式引用適合你已經知道路徑的情況。它的優勢是範圍明確；缺點是你可能漏掉相關檔案。因此複雜問題可以先讓 Gemini CLI 讀結構，再由你確認要引用哪些檔案。

## 2. 讓它自己找檔案

不知道路徑時，不要亂猜：

可以直接問：`Find the file that defines the UserProfile component.`

Gemini CLI 會用目錄列表、glob 等工具探索專案結構，再返回可能路徑。

## 3. 修改和建立檔案

修改檔案：

`Update @src/components/UserProfile.tsx to show a loading spinner if user data is null.`

建立檔案：

`Create a new file @src/components/LoadingSpinner.tsx with a simple Tailwind CSS spinner.`

修改前它會展示 unified diff。你要看清楚再確認。

> [!WARNING]
> **不要一次授權整個目錄重寫**：讓它修改多個檔案前，先要求輸出檔案清單、每個檔案為什麼要改、預期驗證命令。沒有清單的大範圍改動，不適合直接確認。

## 4. .geminiignore

Gemini CLI 預設尊重 `.gitignore`。如果有些檔案不想暴露給 AI，但不適合放進 `.gitignore`，可以用 `.geminiignore`：

常見排除項包括 `.env`、`local-db-dump.sql`、`private-notes.md`。

`.geminiignore` 適合排除本地敏感材料、臨時資料、資料庫 dump、客戶資料和私有筆記。它不應該代替憑據管理；真正的金鑰仍然不能放在專案目錄裡等工具來“忽略”。

## 5. 工具分工

顯式 `@file` 適合你已經知道路徑的情況。路徑不確定時，讓 Gemini CLI 先列目錄、搜尋名稱或搜尋內容；讀單個檔案和批次讀上下文是兩種不同動作；修改優先做精確替換，只有新建檔案或整體重寫時才適合完整寫入。

```mermaid
flowchart TD
    Task["檔案任務"] --> Known{"知道路徑?"}
    Known -->|是| At["@file 精確引用"]
    Known -->|否| Search["先搜尋檔案和目錄"]
    At --> Read["只讀解釋"]
    Search --> Read
    Read --> Plan["修改計劃"]
    Plan --> Edit["限定檔案編輯"]
    Edit --> Diff["看 unified diff"]
    Diff --> Test["跑最小驗證"]

    style Read fill:#dcfce7,stroke:#22c55e
    style Edit fill:#fef3c7,stroke:#f59e0b
    style Diff fill:#dbeafe,stroke:#3b82f6
```

## 6. 安全順序

1. 只讀解釋目錄。
2. 指定單檔案解釋。
3. 讓它提出修改計劃。
4. 只授權一個小檔案修改。
5. 看 diff。
6. 跑測試。

## 7. 驗收方式

編輯檔案前，要求 Gemini CLI 先說清它準備讀哪些檔案和為什麼讀。編輯後檢查 unified diff、執行專案測試或最小驗證命令。涉及 `.geminiignore` 的專案，再驗證被排除檔案不會透過 `@` 或搜尋進入上下文。

## 8. 接下來去哪

<Cards>
  <Card title="Shell 命令" description="檔案能讀寫以後，繼續看如何讓 Gemini CLI 安全執行測試和指令碼。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/14-shell-commands" />
  <Card title="GEMINI.md" description="反覆出現的專案規則不要每次 prompt 複製，繼續沉澱到上下文檔案。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/21-gemini-md" />
  <Card title="gemini ignore" description="繼續看哪些檔案應該排除在 AI 上下文之外。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/23-gemini-ignore" />
</Cards>

## 官方來源

- [Gemini CLI file management tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/file-management.md)
- [Gemini CLI file system tools](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/file-system.md)
