---
title: ".geminiignore"
description: ".geminiignore 的用途：排除敏感檔案、大檔案、構建產物、本地資料庫和不希望 Gemini CLI 讀取的專案內容。"
verifiedAt: "2026-05-09"
---

`.geminiignore` 用來告訴 Gemini CLI 哪些檔案不要讀取或搜尋。官方 file management tutorial 說明：Gemini CLI 預設尊重 `.gitignore`，但你可以用 `.geminiignore` 排除不適合暴露給 AI 的檔案。

> [!WARNING]
> `.geminiignore` 是上下文過濾，不是安全沙箱。不要因為寫了 ignore，就把金鑰、客戶資料或本地資料庫留在 AI 可操作目錄裡。

## 工作機制

`.geminiignore` 的語法基本沿用 `.gitignore`：

- 空行和 `#` 註釋會被忽略。
- 支援 `*`、`?`、`[]` 等 glob。
- 結尾 `/` 只匹配目錄。
- 開頭 `/` 表示相對 `.geminiignore` 所在目錄錨定。
- `!` 可以取消排除。

被排除的路徑會從支援該機制的 Gemini CLI 工具裡過濾掉，例如 `@` 檔案引用、檔案讀取和搜尋。但它不會替你改變 Git、磁碟許可權或第三方服務訪問能力。修改 `.geminiignore` 後需要重啟當前 Gemini CLI 會話才會生效。

官方配置裡還有兩個容易被忽略的開關：`context.fileFiltering.respectGitIgnore` 和 `context.fileFiltering.respectGeminiIgnore`。如果你發現 `@` 引用、`read_many_files` 或搜尋結果和預期不一致，先檢查這兩個開關是否被使用者級、專案級或系統級 settings 覆蓋。

`@<path>` 檔案引用是最常見的觸發點。它會透過多檔案讀取工具把檔案或目錄加入上下文，並按 Git-aware 過濾規則處理。也就是說，`.geminiignore` 不是孤立生效，而是和 `.gitignore`、settings 裡的 fileFiltering、工具引數一起決定最終能看到哪些檔案。

## 推薦模板

```text
.env
.env.*
*.pem
*.key
*.p12
*.sqlite
*.db
*.log
local-db-dump.sql
private-notes.md
coverage/
dist/
build/
node_modules/
```

## 適合排除

- `.env`、憑據、token、私鑰。
- 本地資料庫 dump。
- 私人筆記。
- 大型構建產物。
- 生成檔案。
- 版權敏感或不該進入上下文的素材。

不建議盲目排除所有 Markdown。很多專案規則、README、設計文件都在 Markdown 裡；如果全排除，Gemini CLI 會缺少專案上下文。需要排除文件時，優先排除具體路徑，例如 `/private-notes/`，而不是 `*.md`。

monorepo 裡要特別小心根目錄規則。根 `.geminiignore` 寫得過寬，會同時影響多個 package；如果只有某個子專案有敏感 fixture 或私有匯出檔案，優先在子目錄放更窄的規則，或者用錨定路徑限制影響範圍。

## 和 .gitignore 的區別

| 檔案 | 目的 |
| --- | --- |
| `.gitignore` | 不進入 Git |
| `.geminiignore` | 不進入 Gemini CLI 上下文 |

有些檔案可以進 Git，但不該讓 AI 讀；這時用 `.geminiignore`。

| 檔案型別 | `.gitignore` | `.geminiignore` |
| --- | --- | --- |
| `.env.local` | 應該排除 | 應該排除 |
| `node_modules/` | 應該排除 | 應該排除 |
| `README.md` | 不應排除 | 通常不應排除 |
| 已提交的測試 fixture | 不應排除 | 視是否含敏感資料 |
| 內部客戶案例 | 可能已進 Git | 通常應排除 |

## 常見誤區

- 以為 `.geminiignore` 等於安全沙箱。它只是上下文過濾，不是訪問控制。
- 修改後不重啟會話，然後以為規則無效。
- 只寫 `.gitignore`，忘了儲存庫裡仍可能有已跟蹤的敏感樣例、客戶資料或內部文件。
- 在 monorepo 根目錄寫得過寬，導致子專案的說明文件、schema、測試樣例也被排除。
- 把 `.geminiignore` 當作補救手段，而不是先從儲存庫裡移除不該存在的敏感檔案。

## 驗收方式

重啟 Gemini CLI 後，用 `@` 引用一個被排除檔案，確認它不會被加入上下文。再讓 Gemini CLI 搜尋一個只存在於被排除目錄裡的字串，確認搜尋結果不返回該檔案。最後保留一條允許項測試 `!README.md` 這類反向規則是否符合預期。

如果專案開啟了多入口規則檔案，還要檢查 `context.fileName` 指向的檔案沒有被 ignore 誤傷。規則檔案、README、schema、測試說明通常是 agent 正確工作的基礎，不應該被寬泛規則排除。

## 接下來去哪

<Cards>
  <Card title="Custom commands" description="上下文邊界清楚後，繼續把重複操作做成專案命令。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/24-custom-commands" />
  <Card title="檔案管理" description="回看 @ 檔案引用、目錄上下文和 ignore 的日常用法。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/13-file-management" />
  <Card title="Sandbox" description="需要真正限制檔案系統和命令執行時，繼續看 sandbox。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方來源

- [Gemini CLI .geminiignore](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-ignore.md)
