忽略文件

通过 .cursorignore 和 .cursorindexingignore 控制文件访问

概览

Cursor 会读取并索引你的项目代码库以驱动其功能。使用根目录下的 .cursorignore 文件来控制 Cursor 能访问哪些目录和文件。

Cursor 会在以下场景中阻止访问 .cursorignore 中列出的文件：

• 代码库索引
• Tab、Agent 和 Inline Edit 可访问的代码
• 通过 @ 符号引用 可访问的代码

由 Agent 发起的工具调用（例如 terminal 和 MCP 服务器）无法阻止 访问受 .cursorignore 管控的代码

为什么要忽略文件？

安全：限制对 API 密钥、凭证和机密信息的访问。虽然 Cursor 会屏蔽被忽略的文件，但由于 LLM 具有不可预测性，无法做到完全防护。

性能：在大型代码库或 monorepo 中，排除无关部分以加快索引速度并更准确地发现文件。

全局忽略文件

在用户设置中为所有项目配置忽略模式，无需逐个项目设置即可排除敏感文件。

默认模式包括：

• 环境文件：**/.env、**/.env.*
• 凭据：**/credentials.json、**/secrets.json
• 密钥：**/*.key、**/*.pem、**/id_rsa

配置 .cursorignore

在你的项目根目录里，按 .gitignore 的语法创建一个 .cursorignore 文件。

模式示例

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] 测试匹配规则。