忽略文件（Ignore Files）

概述

Cursor 通过读取并索引项目代码库来驱动其功能。您可以通过在项目根目录添加 .cursorignore文件，控制 Cursor 可访问的目录和文件。

Cursor 将尽最大努力阻止访问 .cursorignore 文件中列出的文件，具体涉及以下场景：

代码库索引
通过 Tab、Chat 和 ⌘K 功能访问代码
通过 @符号引用访问代码

注意

目前，由 Cursor chat 功能发起的工具调用（如 Terminal 和 MCP 服务器）仍可能访问受 .cursorignore 管控的代码

全局忽略文件

您现在可以通过用户级设置定义适用于所有项目的全局忽略规则。这种方式无需逐个项目配置，即可将构建产物或密钥等干扰性/敏感文件排除在提示词之外。

为何需要忽略文件？

通常有以下两个原因需要配置 Cursor 忽略部分代码库：

1. 隐私与安全 当代码库包含敏感信息（如 API 密钥、用户数据或内部工具）时，通过忽略规则可确保这些内容不会意外进入 AI 模型的上下文。

2. 减少干扰 忽略构建产物（如 node_modules/ 或 dist/）和 IDE 配置文件（如 .vscode/）能提升 AI 生成代码的相关性，同时降低 token 消耗。

安全性

在使用 Cursor 处理本地敏感文件时，出于安全考虑（例如包含 API 密钥、数据库凭证和其他机密信息的文件），您可能仍希望限制对某些文件的访问。

Cursor 会尽最大努力阻止对被忽略文件的访问，但由于 LLM 行为存在不可预测性，我们无法保证这些文件永远不会被暴露。

性能优化

如果您在单体仓库（monorepo）或非常庞大的代码库中工作，且其中大部分内容与当前开发代码无关，您可以考虑配置 Cursor 来忽略应用程序的这些部分。

通过排除代码库中无关的部分，Cursor 会：

更快地索引大型代码库
在搜索上下文时更快速精准地定位文件

Cursor 本身设计支持大型代码库，并擅长评估文件相关性。但当您使用的代码库特别庞大或包含与开发无关的文件时，忽略功能将非常有用。

配置 .cursorignore 文件

要启用 Cursor 的忽略功能，请在你的代码库根目录下添加一个 .cursorignore 文件，并列出需要忽略的目录和文件。

.cursorignore 文件使用的模式匹配语法与 .gitignore 文件完全相同。

层级式忽略规则

默认情况下，Cursor 只会在当前工作区中查找 .cursorignore 文件。当在 Cursor Settings > Features > Editor > Hierarchical Cursor Ignore 中启用该功能后，Cursor 将沿文件树向上搜索所有 .cursorignore 文件，从而支持跨嵌套项目目录的更灵活配置。

基础模式示例

# 忽略特定文件 `config.json`
config.json

# 忽略 `dist` 目录及其内部所有文件
dist/

# 忽略所有扩展名为 `.log` 的文件
*.log

高级模式示例

# 忽略整个代码库
*

# 不忽略 `app` 目录
!app/

# 忽略所有目录中的 logs 目录
**/logs

注意事项

空行会被忽略
以 # 开头的行被视为注释并被忽略
模式匹配基于 .cursorignore 文件所在位置的相对路径
当出现模式冲突时，后面的模式会覆盖文件中先前列出的冲突模式

通过 `.cursorindexingignore` 限制索引

若需仅针对索引功能实现 Cursor 的忽略特性，请在代码库目录的根路径下创建 .cursorindexingignore 文件，并在其中列出需要从索引中排除的目录和文件。

列在 .cursorindexingignore 中的文件将不会包含在 Cursor 的索引中，但仍可通过 Cursor 的 AI 辅助功能进行访问，包括当 Cursor 搜索代码库或将其暴露给 LLM 时。

默认忽略的文件

Cursor 会自动忽略以下两类文件：

项目根目录 .gitignore 文件中列出的所有文件
下方提供的默认忽略列表中包含的文件

取消忽略操作：若需要取消忽略上述文件中列出的特定文件，可在 .cursorignore 文件中使用 ! 前缀进行标注。

默认忽略列表

在代码索引过程中，除了 .gitignore、.cursorignore 和 .cursorindexignore 文件中指定的文件外，以下文件类型也会被自动忽略：

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/

故障排除

若需排查忽略文件配置问题，可使用 git check-ignore -v [文件路径] 命令测试模式匹配效果。该命令会显示具体生效的忽略规则及其所在文件路径，帮助您快速定位配置问题。

操作步骤：

在终端中定位到代码库根目录
执行命令：

git check-ignore -v src/test/unwanted-file.js
# 注释示例：此处路径应根据实际文件调整

查看输出结果中的匹配规则

高级技巧

当处理复杂忽略规则时，建议：

使用 ** 通配符进行深度匹配
通过 ! 运算符添加例外规则

常见问题诊断：

若规则未生效，请检查 .gitignore 文件是否位于代码库根目录
确保没有在 .gitignore 文件中重复定义冲突规则
注意不同 .gitignore 文件的优先级（项目级 > 目录级）

概述​

全局忽略文件​

为何需要忽略文件？​

安全性​

性能优化​

配置 .cursorignore 文件​

层级式忽略规则​

基础模式示例​

高级模式示例​

注意事项​

通过 .cursorindexingignore 限制索引​

默认忽略的文件​

故障排除​

概述