这篇讲什么
Cursor 索引调好和没调好的差距是”Cursor 真懂你代码”和”Cursor 老引一些不存在的文件”。这篇是真正的调优循环——忽略什么、什么时候重 index、怎么用 @File / @Folder / @Symbol 精确钉住，以及大代码库会撞上的”索引慢 / 坏”诊断方法。
这篇适合谁看
在中大型代码库里用 Cursor 的人——刚学完入门的小项目之外都算。monorepo、构建产物多、Cursor 开始漏 / 错引文件的项目尤其受益。还没做完基础上手的，先走一遍Cursor 新手 30 分钟跑通完整工作流，再来调索引。
什么时候适合用
发现 Cursor 错引文件、提一些不存在的 symbol、反复漏掉明明存在的文件、或速度突然变慢时。任何大的仓库变更（大 merge、切分支、依赖升级）之后主动跑一次也值得。
开始前准备
- 在 Cursor 设置里看索引状态。记现状（“Indexing…”、“Synced” 或 “Failed”）。
- 标出在拖累索引的东西：构建产物、大数据文件、生成代码、vendor 库、git 历史文件。
- 想清楚真正有信号的目录是哪些——通常是
src/、lib/、app/、pages/——哪些是噪声。 - 知道项目里”生成”和”手写”的边界。生成的代码很少需要索引。
具体步骤
- 仓库根维护严格
.cursorignore。从这套基线起，按需加：
node_modules/
dist/
build/
.next/
.astro/
.cache/
coverage/
*.log
*.map
public/assets/ # 如果是生成的
data/large/ # 大数据文件- 仓库大改后重 index——大 merge、依赖升级、分歧大的切分支。Cursor 设置 → “Re-index repo”。索引陈旧会引出”看似模型失误其实是搜索失误”的错误文件引用。
- 有歧义就显式用
@File/@Folder/@Symbol。“修登录 bug” → “修@File:src/auth/login.ts里的 bug”。@ 提及钉住上下文，绕过索引歧义。 - 别索引构建产物。任何能被 build 步骤重新生成的东西都不该进索引。首次 index 前加
.cursorignore，不是事后加。 - monorepo 按 workspace 打开。工作在
packages/web时打开它，而不是仓库根。 - 索引卡或慢，看索引日志（Cursor 设置 → developer / diagnostics）。常见嫌疑：单个超大文件、深 symlink、加密目录。
一份”索引慢”诊断清单
- 排了
node_modules吗？没排索引时间就被它主导了。 - 有没有超过 10MB 的单文件？Cursor 在单大文件上吃力，gzip 或拆分。
- 有指向仓库外的 symlink 吗？Cursor 可能跟过去把你的 home 都索引一遍。
- 源路径里混了生成文件吗？挪走或忽略。
- git 仓库健康吗（
git fsck）？索引用 git 元数据。
第一次实操怎么跑
- 看当前索引状态。“Synced” 跳到第 3 步。
- 打开
.cursorignore。加上面基线。重 index。计时。中等项目应该 2 分钟内完成。 - 打开 Composer。用
@File引一个文件。确认文件内容进上下文。没进就是忽略规则误排除了它。 - 跑一个引用非琐碎 symbol 的小 Inline 编辑。Cursor 应不靠猜就找到它。
完成后检查
- 索引时间合理（中等项目 5 分钟内，monorepo 15 分钟内）。再久就可疑。
@File引用解析到你预期的文件。- Composer 建议引用的是真 symbol。symbol 名是幻觉就是索引漏文件。
- 私密数据、secrets、构建产物没进上下文。抽查方式：让 Cursor “列出
src/里你能看到的文件”。
怎么复用这套流程
.cursorignore提交到仓库，让队友继承调优。- 大重构（文件大量改位置）之后重新调。旧路径留在索引里会引到错文件。
- 列一份”必须 @ 钉住”的 symbol 和文件——核心配置、关键类型、主入口。任何非琐碎 prompt 都显式提及。
- 季度复测。Cursor 索引策略会变，老
.cursorignore现在可能排得过多或过少。
建议的操作流程
加 .cursorignore → 触发重 index → 用 @ 显式引文件 → 复核 Cursor 看到的 → 仓库大改后再来一轮。
容易踩的坑
- 索引
node_modules。又慢又噪、把库代码塞进上下文。 - 大改后从不重 index。索引会漂，引用会失效。
- 索引一直停在「Indexing…」就放着，以为多等就好（索引一直跑不完）。
- 跨文件编辑靠隐式上下文。用
@提及；索引很好但不会读心。 - 项目级、workspace、用户级
.cursorrules互相冲突，表现是「指令被忽略」，不会报错（Cursor 配置冲突）。 - 索引私钥。
.env、secrets/一类立刻进.cursorignore。
FAQ
- Cursor 索引会离开我的机器吗？: embedding 在 Cursor 远端基础设施上算；文件内容被切块和 hash。敏感代码上索引前看最新隐私文档。
- 多大仓库能索引？: 几万文件配干净
.cursorignore没问题。百万文件的 monorepo 要按 workspace 开。 - 索引完了还漏文件？: 要么被忽略、要么索引陈旧、要么 prompt 没钉够上下文。用
@File验证。 - 每次 commit 后都要重 index 吗？: 不用。Cursor 监听文件系统、增量更新。只在大改后手动重 index。