忽略文件

通过 .cursorignore 和 .cursorindexingignore 文件，控制 Cursor 的 AI 功能和索引能访问哪些文件。

概述

Cursor 会读取并索引你的项目代码库以支持其功能。你可以在项目根目录添加 .cursorignore 文件，控制 Cursor 能访问哪些目录和文件。

Cursor 会尽力阻止 .cursorignore 中列出的文件被以下功能访问：

• 代码库索引
• Tab、Chat 和 ⌘K 可访问的代码
• 通过 @symbol 引用的代码

全局忽略文件

你可以在用户级设置中定义全局忽略模式，让所有项目都适用。这有助于自动排除如构建输出、密钥等敏感或无关文件，无需每个项目单独配置。

为什么要忽略文件？

配置 Cursor 忽略部分代码库的常见原因有两个：

安全性

虽然你的代码库不会永久存储在 Cursor 服务器或 LLM 上，但你可能仍希望出于安全考虑限制某些文件的访问，比如包含 API 密钥、数据库凭证等敏感信息的文件。

Cursor 会尽力阻止访问被忽略的文件，但由于 LLM 行为不可预测，无法保证这些文件绝不会被暴露。

性能

在 monorepo 或超大代码库中，如果有大量与当前开发无关的部分，可以通过忽略这些部分提升索引速度和上下文检索效率。

通过排除无关的代码库部分，Cursor 能更快地索引大型代码库，并在查找上下文时以更高的速度和准确性定位文件。

Cursor 设计之初就支持大型代码库，并且擅长评估文件的相关性，但当你的代码库特别庞大或包含许多与开发无关的文件时，忽略功能会非常有用。

配置 .cursorignore

在代码库根目录添加 .cursorignore 文件，列出要忽略的目录和文件。
其语法与 .gitignore 完全一致。

层级忽略
默认只查找当前工作区的 .cursorignore 文件。你可以在 Cursor Settings > Features > Editor > Hierarchical Cursor Ignore 启用层级查找，让 Cursor 向上查找所有 .cursorignore 文件，实现更灵活的嵌套项目配置。

基本模式示例

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

# 忽略 dist 目录及其所有内容
dist/

# 忽略所有 .log 文件
*.log

高级模式示例

# 忽略整个代码库
*

# 不忽略 app 目录
!app/

# 忽略任意目录下的 logs 目录
**/logs

注意事项：

• 空行会被忽略
• 以 # 开头的行为注释
• 模式相对于 .cursorignore 文件位置匹配
• 后面的模式会覆盖前面冲突的模式

限制索引：.cursorindexingignore

如果只想限制索引而不影响 AI 功能，可以在代码库根目录添加 .cursorindexingignore 文件，列出要排除在索引之外的目录和文件。

被 .cursorindexingignore 列出的文件不会被 Cursor 索引，但仍可被 AI 辅助功能访问（如代码检索和 LLM 上下文）。

默认被忽略的文件

Cursor 还会自动忽略你根目录下 .gitignore 文件中列出的所有文件，以及下方提供的默认忽略列表中的文件。

如果你希望某个被这些文件忽略的文件不被忽略，可以在 .cursorignore 文件中用 ! 前缀将其添加进来。

故障排查

如果你在使用忽略文件时遇到问题，可以使用 git check-ignore -v [file] 命令测试你的模式是否生效。