.cursorignore 怎么写？缩小索引、省 Token、保护敏感文件
.cursorignore 是放在项目根目录的一份”屏蔽清单”，用来告诉 Cursor 哪些文件不要读、不要发给模型、也不要纳入索引。 语法和 .gitignore几乎一样，但作用对象不是 Git，而是 AI——写好它能同时做到三件事：让代码库索引更小更准、对话时少烧 Token、把 .env 这类密钥挡在模型之外。
如果你用 Cursor 时遇到过索引很慢、AI 总引用一堆无关文件、或者担心密钥被上传，这篇就是给你的。下面把原理、写法、模板和排查一次讲透。
原理：.cursorignore 到底拦住了什么
要写对，先得知道它拦的是什么。Cursor 在两个环节会”看”你的文件：
- 建立代码库索引：Cursor 会扫描项目、把代码切块做成向量索引，这样
@Codebase、Agent 检索才能找到相关代码。 - 把上下文发给模型：你提问、
@文件、或 Agent 自动抓取上下文时，文件内容会被发送到云端大模型。
.cursorignore 的作用是在这两个环节同时把命中的文件排除掉——既不进索引，AI 也读不到、发不出去。所以它有双重价值：
- 省 Token / 提速：
node_modules、构建产物、日志这类几十万行的垃圾不进索引，检索更快更准，对话上下文也不会被它们挤占。 - 保护敏感文件：
.env、私钥、客户数据被它挡住，就不会随对话上传到模型服务商。
关键认知：这是给 AI 看的屏蔽清单，不是给 Git 看的。它不影响版本控制，
.gitignore也不会自动替它生效——两份文件各管各的。
通用写法：语法和 .gitignore 一致
新建一个名为 .cursorignore 的文件，放在项目根目录（和 .gitignore 同级），按行写规则即可：
# 依赖与构建产物（最该排除的）
node_modules/
dist/
build/
.next/
out/
target/
# 日志与缓存
*.log
.cache/
coverage/
# 敏感文件（保护密钥）
.env
.env.*
*.pem
*.key
secrets/
# 大文件 / 二进制 / 数据集
*.zip
*.mp4
*.sqlite
data/
# 锁文件（很长且无信息量）
pnpm-lock.yaml
package-lock.json
yarn.lock
语法要点（和 .gitignore 同源）：
| 写法 | 含义 |
|---|---|
node_modules/ | 末尾加 / 表示只匹配目录 |
*.log | * 通配，匹配所有 .log 文件 |
build/** | ** 递归匹配多层目录 |
# 注释 | # 开头是注释 |
!keep.env.example | ! 取反，保留某个本来被排除的文件 |
/config.ts | 开头加 / 锚定根目录，只匹配根下的该文件 |
最省事的起点：直接把 .gitignore 的内容拷过来，再补上你不想让 AI 看到的敏感目录。
分场景模板：不同技术栈该排除什么
通用模板只覆盖了最大公约数，实际项目里该排除的东西跟技术栈强相关。下面几套是我在不同项目里实际在用的，直接抄作业就行：
Python 项目
__pycache__/
*.pyc
.venv/
venv/
.pytest_cache/
.mypy_cache/
*.egg-info/
.tox/
Java / Kotlin（Maven、Gradle）
target/
.gradle/
build/
*.class
.idea/
移动端（Android / iOS）
# Android
.gradle/
app/build/
*.apk
# iOS
Pods/
DerivedData/
*.xcworkspace
Monorepo（多个子包各有 dist）
packages/*/dist/
packages/*/build/
apps/*/.next/
apps/*/node_modules/
Monorepo 里最容易漏的是每个子包各自的 node_modules 和 dist——只写一条根目录的 node_modules/ 挡不住 packages/xxx/node_modules，得用 packages/*/node_modules/ 这种带通配符的路径，或者干脆用 **/node_modules/ 递归排除所有层级。
.cursorignore 和 .cursorindexingignore 的区别
这是最容易搞混的一点，很多人写错就是没分清这两份文件。简单记一句话：
.cursorignore：彻底屏蔽——既不索引，AI 也读不到。用于密钥、敏感数据这类”碰都不能碰”的文件。.cursorindexingignore：只是不进索引，但需要时 AI 仍可读取/被你手动@引用。用于”不必检索、但偶尔要看”的大文件或生成代码。
| 需求 | 该用哪个 |
|---|---|
.env、私钥，绝不能上传 | .cursorignore |
node_modules、构建产物，纯垃圾 | .cursorignore |
| 自动生成的超大文件，平时不检索但偶尔要看 | .cursorindexingignore |
| 想缩小索引但保留手动引用能力 | .cursorindexingignore |
拿不准时的口诀：敏感就用
.cursorignore，只是嫌大就用.cursorindexingignore。两份文件的具体行为以官方文档为准，Cursor 各版本的实现细节可能微调。
怎么验证写得对不对
写完别急着信，花一分钟验证：
- 重建索引看耗时：在 Cursor 设置里找到代码库索引（Codebase Indexing），重新索引，看文件数和耗时是否明显下降。排除掉
node_modules后，大型前端项目的索引文件数通常会断崖式减少。 - 测敏感文件是否被挡：在对话里
@你写进.cursorignore的.env，正常情况应当无法被读取或提示已被忽略。 - 测 AI 检索质量：问一个之前会被无关文件干扰的问题，看 AI 是否还在引用
dist/里的编译产物。
常见坑与排查
| 现象 | 原因 | 解法 |
|---|---|---|
写了规则但 .env 还能被读 | 文件名/路径不对，或放错目录 | 确认文件名是 .cursorignore（前面有点）、在项目根目录 |
| 索引还是很慢、很大 | 规则没生效，未重建索引 | 改完手动触发”重新索引” |
| 排除了某目录但还想保留一个文件 | 缺少取反规则 | 用 ! 写例外，如 !.env.example |
| 整个项目几乎搜不到代码 | 规则写太狠，把源码也排除了 | 检查是否误写了 src/ 或过宽的 * |
| AI 仍引用编译产物 | dist/build 没排除干净 | 补 dist/ build/ out/ 等产物目录 |
| 改了文件没反应 | 编辑器未重读配置 | 重载窗口或重启 Cursor |
如果你排除了 node_modules 后索引依旧异常、@Codebase 检索结果不对，那可能不是 ignore 的问题，而是索引本身坏了——排查思路见 Cursor 索引失败怎么修（规划中）。
实测：排除前后差多少，不是玄学
拿一个中等规模的 Next.js 项目举例：源码文件大概 300 个，加上 node_modules 之后，项目里的总文件数轻松破 8 万。
- 不排除任何东西：索引文件数常常冲到六位数，首次建索引要跑上好几分钟；问一句业务逻辑，Cursor 有概率把某个三方库里同名的工具函数当成候选塞进上下文，回答开始”文不对题”。
- 只加两条规则（
node_modules/、.next/）：索引文件数直接掉回 300 左右，索引时间从几分钟压到几十秒，@Codebase检索基本不再跑偏。
这不是玄学，是文件数量级的差距——把 90% 以上跟业务无关的文件挡在外面，AI 自然只在真正相关的那一小撮源码里找答案，速度和准确率都跟着上去。反过来说，如果你的项目现在检索质量差、经常给你答非所问的引用，先别急着怀疑模型能力，大概率是 .cursorignore 没写或者写漏了。
进阶：和 Rules 配合，让 AI 更听话
.cursorignore 管”不让 AI 看什么”，Cursor Rules（规划中）则管”让 AI 怎么做”。两者搭配是工程化用 Cursor 的标配：
- 用
.cursorignore把噪音和密钥挡在外面，保证上下文干净； - 用
.mdc规则文件约定代码风格、技术栈、目录约定，保证产出统一。
先把 ignore 写好，再补 Rules，AI 的输出质量会有肉眼可见的提升。
常见问题
Q：.cursorignore 和 .gitignore 是同一个东西吗？
不是。.gitignore 管 Git 版本控制，.cursorignore 管 AI 读取与索引。语法一样，但作用对象不同，需要分别维护。你可以把 .gitignore 内容拷进去当起点，再补敏感文件。
Q：写了 .cursorignore，密钥就一定安全了吗？
它能阻止文件被索引和发给模型，是必要的一道防线，但不是绝对保险。真正的密钥不应硬编码进代码库，建议配合环境变量管理和 .gitignore。涉及合规的敏感数据，以官方对忽略文件行为的说明为准。
Q：放在子目录里有用吗？
建议放在项目根目录最稳妥。Cursor 主要读取根目录的 .cursorignore。如果你的项目是 monorepo，把要排除的子包路径写进根目录这一份即可，例如 packages/*/dist/。
Q：排除了文件，AI 还能完成任务吗？
能，而且通常更好。排除的本就是 node_modules、构建产物这类对理解业务逻辑没价值的噪音。排除它们后，AI 检索更聚焦真正的源码，回答质量反而提升。只要别误删 src/ 这类核心目录就行。
👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。