忽略文件

Cursor 会读取项目的代码库，以提供相关功能。使用根目录中的 .cursorignore 文件控制 Cursor 可访问的目录和文件。

Cursor 会禁止以下功能访问 .cursorignore 中列出的文件：

• Agent、Tab 和 Inline Edit 可访问的代码
• 可通过 @ 提及引用 访问的代码

为什么要忽略文件？

安全性：限制对 API 密钥、凭据和机密信息的访问。虽然 Cursor 会阻止访问已忽略的文件，但由于 LLM 的不可预测性，无法保证完全防护。

性能：对于大型代码库或单体仓库，排除无关部分可提升文件发现的准确性。

配置 .cursorignore

在根目录中创建 .cursorignore 文件，并使用 .gitignore 语法。

匹配模式语法

• * 匹配除 / 外的任意字符
• ** 匹配包括 / 在内的任意字符
• ? 匹配单个字符
• ! 用于否定模式 (取消忽略之前已忽略的路径)
• 以 # 开头的行是注释
• 除非用 \ 转义，否则会忽略行尾空格

模式示例

config.json      # 指定文件dist/           # 目录*.log           # 文件扩展名**/logs         # 嵌套目录!app/           # 不忽略（取反）

分层忽略

启用 Cursor Settings > Features > Editor > Hierarchical Cursor Ignore，即可在父级目录中查找 .cursorignore 文件。

全局忽略文件

在用户设置中为所有项目设置忽略模式，无需为每个项目单独配置，即可排除敏感文件。全局忽略列表默认为空。

常见的模式包括：

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

默认忽略的文件

Cursor 会自动忽略 .gitignore 和下方默认忽略列表中的文件。可在 .cursorignore 中使用 ! 前缀取消忽略。

package-lock.jsonpnpm-lock.yamlyarn.lockcomposer.lockGemfile.lockbun.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] 检查模式。