一句话总结
索引调好和没调好的差距，就是”Cursor 真懂你的仓库”和”Cursor 老引一些不存在的文件”。三个动作能解决九成索引问题：（1）用 .cursorignore / .cursorindexingignore 把构建产物、缓存、密钥挡在索引外；（2）仓库大改后手动重 index，而不是干等 5 分钟自动同步；（3）用 @File / @Folder / @Symbol 显式钉住上下文，别让 Agent 靠猜。下面是完整循环，全部对照 Cursor 官方文档核实于 2026 年 6 月。
先搞懂索引怎么运作（这样修起来才有道理）
Cursor 建的是语义索引，不是纯文本搜索。打开一个 workspace 后，它用 tree-sitter 把代码切成逻辑块（函数、类、代码块），把每块转成向量 embedding，存进一个远端向量数据库。提问时你的问题也变成向量，最接近的几块被拉进上下文。语义搜索大约在索引完成 80% 时可用，之后每 5 分钟自动同步一次，只对改动过的文件重新 embedding（Cursor 用 Merkle 树的根 hash 来定位它们）。
对调优来说，有两点要记牢：
- 索引陈旧不会报错，只会引错文件。 某个文件的 embedding 过期了，或者根本没被索引，Cursor 就会拉它手头最接近的那一块——看起来像一本正经地胡说。其实模型没出错，是搜索出错了。
- 源码不以明文存储。 据 Cursor 文档，代码只在索引期间留在内存里，之后丢弃；embedding 存储时不带文件名和原始源码，文件路径在传输中加密。这点让人安心，但不等于可以索引密钥（见安全那节）。
大多数人都搞错的一个区别
有两个忽略文件，作用完全不同。混淆它们，是”我明明排了它，Cursor 还是去碰”最常见的原因。
| 文件 | 挡住什么 | 用在哪 |
|---|---|---|
.cursorignore | 所有 AI 访问——索引、Tab 补全、Agent、Inline Edit、以及 @ 提及。文件对 Cursor 完全隐形。 | 密钥，以及任何 AI 永远不该读的东西。 |
.cursorindexingignore | 只挡索引。 文件仍可被 Agent 读、可 @ 提及，但不会出现在语义搜索里。 | 偶尔会打开、但绝不想污染搜索的大段生成代码。Cursor 0.46 起加入。 |
两者都用 .gitignore 语法（*、**、?，以及 ! 取反）。Cursor 还会自动遵守你的 .gitignore，外加一份内置默认清单，已经覆盖了 node_modules、.git、__pycache__、.next、lock 文件、二进制文件和 .env*。所以大多数”想当然”的忽略其实是多余的——你真正要管的，是默认清单漏掉的、项目特有的噪声。
一份真正有用的 .cursorignore 基线
既然默认已经覆盖了 node_modules、lock 文件和 .env*，你的文件就该聚焦在你自己的噪声上——混在源码目录里的生成产物和大数据：
# 落到源码目录里的生成 / 构建产物
dist/
build/
coverage/
.astro/
storybook-static/
public/assets/ # 仅当这些是生成的
src/generated/ # codegen 输出
# 撑大 embedding 的重数据
data/large/
*.parquet
fixtures/**/*.json # 大的客户数据 fixture
# 默认 .env* 之外的额外密钥位置
secrets/
**/credentials.json
**/service-account*.json把这个文件提交到仓库，队友就能继承这份调优。monorepo 可以用分层忽略（在设置里开启”Hierarchical Cursor Ignore”），让 packages/web/ 里的 .cursorignore 只管这个包。
安全：忽略一个文件 ≠ 保护它
立刻把 .env、secrets/、密钥文件、凭据 JSON 加进 .cursorignore。但要清楚它的边界，因为社区里泄露的反馈一直有：.cursorignore 只是阻止文件被索引，Agent 在它认为需要时，仍能用文件系统工具直接打开它。 如果某个路径放着真密钥，就把它彻底移出工作目录——挪到环境变量或密钥管理服务里——别只靠忽略文件。把 .cursorignore 当成降噪手段，而不是访问控制。
调优循环，一步步来
- 先看状态。 Cursor Settings → Indexing & Docs。看它显示 Indexing、Synced 还是 Failed，并用”View included files”确认索引里到底有什么。要是你的密钥或
dist/出现在里面，说明忽略规则没生效。 - 在首次索引之前就加好
.cursorignore，别事后补。垃圾一旦被 embedding 了，就会一直留着，直到你重 index。 - 大改后重 index。 大 merge、分歧大的切分支、依赖升级，都会让索引陈旧得比 5 分钟同步能优雅处理的速度更快。Cursor Settings → Indexing → 重新索引。干净的中等项目（几千文件）应该远在 2 分钟内完成。
- 关键处显式钉住上下文。 别写”修登录 bug”，写”修
@File:src/auth/login.ts里的 bug”。@File、@Folder、@Symbol完全绕过语义歧义——内容直接注入，不走搜索。 - monorepo 按 workspace 打开。 百万文件的 monorepo，打开具体的包（比如
packages/web），而不是仓库根，这样索引才快、搜索才相关。
索引卡住或慢：一份诊断清单
从上往下查，第一个命中的通常就是原因。
node_modules（和其他构建产物）真的排掉了吗？ 用”View included files”确认。排掉它常常能把冷启动索引从几分钟降到 1 分钟内。- 有没有超过几 MB 的单文件？ 超大单文件（打包的 vendor JS、生成的 schema、压缩的 map）会卡住分块。拆分、gzip 或忽略它。
- 有指向仓库外的 symlink 吗？ Cursor 可能跟过去，试图把你的 home 目录都索引一遍。删掉或忽略。
- 生成文件混进
src/了吗？ 挪走，或加进.cursorindexingignore。 - 小仓库却卡在”Setting up indexing…”或”Resyncing index”超过 10 分钟？ 这就不是”多等等”的范畴了——通常是本地缓存损坏、鉴权出问题，或操作系统 file-watcher 上限。清缓存和重新同步的步骤见索引一直跑不完和Cursor 一直 indexing。
作个参照：真正的大仓库（1 万文件以上）首次索引花 10–30 分钟是合理的。之后增量同步应该接近即时——如果不是，就有问题。
5 分钟验证你的配置
- 打开 Cursor Settings → Indexing & Docs，读状态。
- 加上面的
.cursorignore基线，重 index 并计时。再对照 View-included-files 清单——你的生成目录应该消失了。 - 打开 Agent / Composer，用
@File引一个已知文件。确认它的内容进了上下文。没进，就是某条忽略规则误排除了它。 - 跑一个点名非琐碎 symbol 的小 Inline Edit。Cursor 应该能解析到它、而不是凭空造个签名。symbol 名是幻觉，就说明索引漏了那个文件。
容易踩的坑
- 混淆两个忽略文件。 把密钥放进
.cursorindexingignore，Agent 照样能完整读到。密钥要进.cursorignore（最好直接移出仓库）。 - 移动文件的重构之后从不重 index。 旧路径滞留在索引里，引出”看似模型失误”的错误引用。
- 跨文件编辑也信任索引。 它很好，但不会读心——任何非琐碎 prompt 都把核心配置、关键类型、主入口
@钉上。 - 把默认项又抄一遍。
node_modules、.git、lock 文件、.env*本就被忽略，往.cursorignore里塞它们只会淹没真正重要的条目。 - 项目 / workspace / 用户三级
.cursorrules互相冲突。 表现是”指令被忽略”，从不报错（Cursor 配置冲突）。
FAQ
- 我的代码会离开本机吗？: embedding 在 Cursor 的远端基础设施（向量数据库）上计算和存储，但据 Cursor 文档，原始源码只在索引期间留在内存、之后丢弃，embedding 存储不带文件名和源码，路径在传输中加密。涉及合规代码前，先看最新的隐私与安全文档。
.cursorignore和.cursorindexingignore我该用哪个？:.cursorignore让文件对所有 AI 功能隐形；.cursorindexingignore只是把它挡在语义搜索外，仍可被读、可@提及。前者给密钥，后者给那些偶尔会打开的大文件。- 每次 commit 后都要重 index 吗？: 不用。Cursor 每 5 分钟自动同步，只对改动文件重新 embedding。手动重 index 是给大的结构性变更（大 merge、切分支、依赖升级）用的——你不想干等漂移自己消化。
- 索引完了为什么还漏文件？: 三种可能之一——被忽略了、索引陈旧、或你的 prompt 没钉够上下文。用
@File验证：内容出现了，就说明问题在搜索、不在模型。 - 多大的仓库能索引？: 几万文件配干净
.cursorignore没问题；1 万文件以上的仓库首次索引可能要 10–30 分钟。百万文件的 monorepo 应按 workspace 打开，而不是开仓库根。