跳轉到主要內容

​
概覽

Cursor 會讀取並為你的專案程式碼庫建立索引，以驅動各種功能。用根目錄的 .cursorignore 檔案來控制 Cursor 能存取哪些目錄與檔案。 Cursor 會阻擋 .cursorignore 中列出的檔案被以下途徑存取：
由 Agent 發起的工具呼叫（例如 terminal 與 MCP server）無法阻擋 對受 .cursorignore 規範的程式碼的存取

​
為什麼要忽略檔案？

安全性：限制對 API 金鑰、憑證與機密的存取。雖然 Cursor 會封鎖被忽略的檔案，但因 LLM 具不可預測性，仍無法保證絕對防護。 效能：在大型程式碼庫或單一倉庫（monorepo）中，排除無關部分，可加速索引並提升檔案探索的準確度。

​
全域忽略清單

在使用者設定中替所有專案設定忽略模式，免去逐一專案設定即可排除敏感檔案。
Global Cursor Ignore List
預設模式包含：
  • 環境檔：**/.env, **/.env.*
  • 憑證：**/credentials.json, **/secrets.json
  • 金鑰：**/*.key, **/*.pem, **/id_rsa

​
設定 .cursorignore

在專案根目錄建立一個 .cursorignore 檔案，採用 .gitignore 的語法。

​
範例樣式

config.json      # 特定檔案
dist/           # 目錄
*.log           # 檔案副檔名
**/logs         # 巢狀目錄
!app/           # 取消忽略（否定）

​
階層式忽略

啟用 Cursor Settings > Features > Editor > Hierarchical Cursor Ignore，就會在父層目錄中搜尋 .cursorignore 檔案。 注意：註解以 # 開頭。後面的模式會覆寫前面的模式。模式是相對於檔案所在位置的。

​
使用 .cursorindexingignore 限制索引

用 .cursorindexingignore 將檔案排除在索引之外。這些檔案仍可被 AI 功能存取，但不會出現在程式碼庫搜尋結果中。

​
預設會忽略的檔案

Cursor 會自動忽略 .gitignore 中的檔案，以及下方的預設忽略清單。可在 .cursorignore 中使用 ! 前綴覆寫。
僅用於索引時，除 .gitignore、.cursorignore 和 .cursorindexingignore 中的規則外，以下檔案也會被忽略：
package-lock.json
pnpm-lock.yaml
yarn.lock
composer.lock
Gemfile.lock
bun.lockb
.env*
.git/
.svn/
.hg/
*.lock
*.bak
*.tmp
*.bin
*.exe
*.dll
*.so
*.lockb
*.qwoff
*.isl
*.csv
*.pdf
*.doc
*.doc
*.xls
*.xlsx
*.ppt
*.pptx
*.odt
*.ods
*.odp
*.odg
*.odf
*.sxw
*.sxc
*.sxi
*.sxd
*.sdc
*.jpg
*.jpeg
*.png
*.gif
*.bmp
*.tif
*.mp3
*.wav
*.wma
*.ogg
*.flac
*.aac
*.mp4
*.mov
*.wmv
*.flv
*.avi
*.zip
*.tar
*.gz
*.7z
*.rar
*.tgz
*.dmg
*.iso
*.cue
*.mdf
*.mds
*.vcd
*.toast
*.img
*.apk
*.msi
*.cab
*.tar.gz
*.tar.xz
*.tar.bz2
*.tar.lzma
*.tar.Z
*.tar.sz
*.lzma
*.ttf
*.otf
*.pak
*.woff
*.woff2
*.eot
*.webp
*.vsix
*.rmeta
*.rlib
*.parquet
*.svg
.egg-info/
.venv/
node_modules/
__pycache__/
.next/
.nuxt/
.cache/
.sass-cache/
.gradle/
.DS_Store/
.ipynb_checkpoints/
.pytest_cache/
.mypy_cache/
.tox/
.git/
.hg/
.svn/
.bzr/
.lock-wscript/
.Python/
.jupyter/
.history/
.yarn/
.yarn-cache/
.eslintcache/
.parcel-cache/
.cache-loader/
.nyc_output/
.node_repl_history/
.pnp.js/
.pnp/

​
否定模式的限制

使用否定模式（以 ! 作為前綴）時，如果父目錄是透過 * 排除的，就不能重新把某個檔案包含進來。 
# 忽略 public 資料夾中的所有檔案
public/*

# ✅ 這可行，因為該檔案位於頂層
!public/index.html

# ❌ 這不可行—無法從巢狀目錄重新包含檔案
!public/assets/style.css
替代方案：明確排除巢狀目錄： 
public/assets/*
!public/assets/style.css # 這個檔案現在可被存取
為了提升效能，不會遍歷已排除的目錄，所以其中檔案的匹配規則不會生效。 這與 .gitignore 在巢狀目錄中對否定匹配的實作一致。想了解更多，請參考Git 官方文件的 gitignore 規則說明。

​
疑難排解

用 git check-ignore -v [file] 測試忽略規則。
⌘I