---
title: "檔案系統工具"
description: "Gemini CLI 檔案系統工具的使用邊界：讀取、搜尋、寫入、替換、diff 確認、.geminiignore 和敏感檔案排除。"
verifiedAt: "2026-05-09"
---

檔案系統工具讓 Gemini CLI 能看到真實專案。它可以讀取、搜尋、寫入和替換檔案，但寫操作必須更謹慎。

> [!WARNING]
> 檔案系統工具的風險取決於當前目錄。進入 repo 根目錄、home 目錄、下載目錄，工具能看到的範圍完全不同。

所有檔案系統工具都執行在 `rootDirectory` 之內，也就是當前工作目錄或 workspace root。這個邊界很重要：你進入哪個目錄，Gemini CLI 看到的專案範圍就從哪裡開始。

## 常見能力

- 列目錄。
- 搜尋檔案。
- 讀取檔案。
- 寫新檔案。
- 替換區域性內容。
- 展示 diff。

## 工具分工

- `list_directory`：列出某個目錄下的檔案和子目錄，適合第一次探索專案。
- `read_file`：讀取指定檔案，支援 offset 和 limit，適合讀取長檔案的一部分。
- `glob`：按 pattern 找檔案，預設尊重常見忽略規則，適合不知道具體路徑時先定位。
- `grep_search`：按正則搜尋文本，適合查符號、配置項、錯誤資訊。
- `write_file`：建立或覆蓋檔案，屬於寫操作，必須確認。
- `replace`：精確替換檔案中的一段文本，預設要求只匹配一次，適合小範圍補丁。

官方工具名在不同 UI 和實現層裡可能顯示為 `read_file`、`write_file`、`glob`、`search_file_content`、`replace`、`list_directory`。寫教程時建議同時寫“使用者看到的動作”和“官方工具名”，否則讀者排查日誌、policy 或 MCP 輸出時會對不上。

幾個細節要特別說明：`write_file` 會在確認前展示 diff；`replace` 需要 `old_string` 足夠唯一，必要時用 `expected_replacements` 控制替換次數；`read_file` 可讀取文本指定行段，圖片和 PDF 會按工具能力轉成可處理內容，其他二進位制型別可能被跳過或截斷。

## 推薦順序

真實專案裡不要先寫檔案。更穩的順序是：先 `list_directory` 看結構，再用 `glob` / `grep_search` 定位目標，再 `read_file` 讀取相關上下文，最後才考慮 `replace` 或 `write_file`。

`replace` 比整檔案覆蓋更適合維護型修改，因為它要求提供明確舊文本和新文本。批次替換前要讓 Gemini CLI 說明會匹配幾處，避免誤改相似片段。

| 動作 | 風險 | 推薦控制 |
| --- | --- | --- |
| `list_directory` / `glob` | 暴露目錄結構 | 在正確專案目錄啟動 |
| `grep_search` | 暴露匹配內容 | 先配置 `.geminiignore` |
| `read_file` | 讀取敏感檔案 | 限定具體路徑和範圍 |
| `replace` | 誤改相似文本 | 要求唯一匹配和 diff |
| `write_file` | 覆蓋或新增檔案 | 先說明路徑、內容和原因 |

## 安全做法

1. 第一次只讀。
2. 修改前要求它說明影響檔案。
3. 每次只授權小範圍改動。
4. 看 diff。
5. 跑測試。
6. 敏感檔案放進 `.geminiignore`。

## 不該讀取的檔案

```text
.env
*.pem
*.key
local-db-dump.sql
customer-data/
```

## 多檔案讀取邊界

批次讀取不是簡單傳一個目錄。官方 `read_many_files` 要求使用檔案路徑或 glob pattern，例如 `docs/*.md`、`src/**/*.ts`；只傳目錄路徑通常得不到你以為的完整內容。讀取圖片、PDF、音訊、影片這類檔案時，最好顯式寫檔名或副檔名。

預設排除規則會過濾 `node_modules`、`.git` 和常見二進位制檔案；`respect_git_ignore` 預設會尊重 `.gitignore`。如果教程要讓讀者復現“讀取整個專案上下文”，必須寫清 include/exclude pattern，不能只說“讓 Gemini 讀專案目錄”。

## 驗收方式

檔案系統工具的驗收不只看“模型說改好了”。至少要看 diff、確認寫入檔案屬於本次任務範圍，並執行對應檢查命令。多 agent 併發時，每批寫入前後都要檢查 `git status --short <目標目錄>`，防止覆蓋別人正在改的檔案。

## 接下來去哪

<Cards>
  <Card title="Shell 工具" description="檔案讀寫之後，繼續看如何安全執行測試和指令碼。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/32-shell-tool" />
  <Card title=".geminiignore" description="敏感檔案和生成檔案要先從上下文中過濾掉。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/23-gemini-ignore" />
  <Card title="Sandbox" description="需要真正限制檔案系統訪問時，繼續看 sandbox。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方來源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
