Cursor 会读取并索引项目的代码库，以提供相关功能。使用根目录中的 .cursorignore 文件控制 Cursor 可访问的目录和文件。
Cursor 会禁止以下功能访问 .cursorignore 中列出的文件：
Agent 使用的终端和 MCP 服务器工具无法阻止访问
不受 .cursorignore 限制的代码
为什么要忽略文件？¶
安全性：限制对 API 密钥、凭据和机密信息的访问。虽然 Cursor 会阻止访问已忽略的文件，但由于 LLM 的不可预测性，无法保证完全防护。
性能：对于大型代码库或单体仓库，排除无关部分可加快索引，并提升文件发现的准确性。
配置 .cursorignore¶
在根目录中创建 .cursorignore 文件，并使用 .gitignore 语法。
匹配模式语法¶
*匹配除/外的任意字符**匹配包括/在内的任意字符?匹配单个字符!用于否定模式 (取消忽略之前已忽略的路径)- 以
#开头的行是注释 - 除非用
\转义，否则会忽略行尾空格
模式示例¶
config.json # 指定文件
dist/ # 目录
*.log # 文件扩展名
**/logs # 嵌套目录
!app/ # 不忽略（取反）
分层忽略¶
启用 Cursor Settings > Features > Editor > Hierarchical Cursor Ignore，即可在父级目录中查找 .cursorignore 文件。
从 Cursor 3.11 起，此设置将移至 Cursor Settings > Indexing > Ignore Files > Hierarchical Cursor Ignore。
全局忽略文件¶
在用户设置中为所有项目设置忽略模式，无需为每个项目单独配置，即可排除敏感文件。全局忽略列表默认为空。
常见的模式包括：
- 环境文件：
**/.env、**/.env.* - 凭据：
**/credentials.json、**/secrets.json - 密钥：
**/*.key、**/*.pem、**/id_rsa
.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] 检查模式。
