.geminiignore

.geminiignore 用來告訴 Gemini CLI 哪些檔案不要讀取或搜尋。官方 file management tutorial 說明：Gemini CLI 預設尊重 .gitignore，但你可以用 .geminiignore 排除不適合暴露給 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、工具引數一起決定最終能看到哪些檔案。

推薦模板

.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 的區別

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

常見誤區

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

驗收方式

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

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

接下來去哪

官方來源

• Gemini CLI .geminiignore