跳到主要内容

Cursor 代码库索引：怎么让它更好用

Cursor 的代码库索引就是让它对你的项目"开窍"的关键。索引正常工作的时候，你能拿到相关的建议、准确的 @提及、真正理解你架构的回答。索引出问题的时候，Cursor 就像个瞎子。

这篇指南会解释索引是怎么工作的，以及如何优化它。

Cursor 是怎么理解你的代码库的​

Cursor 在后台会构建两样东西：

  1. 嵌入（Embeddings）——代码文件的向量表示。当你提问或用 @ 时，Cursor 会搜索这些向量，找出语义上最相关的文件。

  2. AST（抽象语法树）分析——Cursor 会解析你的代码，理解导入关系、函数定义、类层次结构以及文件之间的关联。

这两套系统协同工作。嵌入负责找到"看起来相关的"，AST 分析负责理清"实际上是怎么连在一起的"。

信息

索引在你打开项目时自动进行。对于大型代码库，初次扫描可能需要几分钟。状态栏里会有进度指示器。

@符号：正确的打开方式​

@ 符号是你直接调用 Cursor 索引的入口。用它来把特定上下文拉进聊天或内联编辑。

@file - 引用特定文件​

@src/utils/auth.ts token 验证是怎么做的？

这是确保 Cursor 看到你关心的那个文件的最可靠方式。它绕过了嵌入搜索，直接附加完整文件内容（在上下文限制内）。

@folder - 引用整个目录​

@src/components 解释一下这里的组件层次结构

适合问架构问题，但要小心——大文件夹会很快吃掉你的上下文窗口。

@code - 引用特定符号​

@code:validateUser 这个函数处理了哪些边界情况？

这个会用 AST 索引来找到精确的函数、类或变量定义。精准又省上下文。

提示

如果你只需要一个函数，优先用 @code: 而不是 @file。能省下上下文空间，减少噪音。

大型项目的优化​

如果你的项目有几千个文件，默认索引可能会漏东西或者感觉很慢。

检查实际索引了什么​

打开 Cursor Settings > General > Codebase Indexing。你会看到：

  • 已索引文件总数
  • 上次索引时间
  • 解析失败的文件

提高上下文相关性​

对于 monorepo，Cursor 有时会抓到不相关的文件。在提示词里明确一点：

只看 @packages/api/src 来回答这个问题。忽略前端代码。

拆分巨型文件​

超过几千行的文件可能会出问题。Cursor 可能只索引开头，或者嵌入处理困难。如果你有个 5000 行的工具文件，考虑拆分一下。

用 .cursorignore 排除文件​

不是所有东西都应该被索引。生成的文件、构建产物、第三方代码会浪费上下文空间，污染搜索结果。

在项目根目录创建 .cursorignore 文件：

# 构建产物
dist/
build/
.out/

# 依赖
node_modules/
vendor/

# 生成文件
*.generated.ts
*.min.js
coverage/

# 大型数据文件
*.csv
*.json
注意

.cursorignore 的语法和 .gitignore 一样，但它是独立的文件。别以为你的 .gitignore 就够了——Cursor 不会自动尊重它。

编辑完 .cursorignore 后，重启 Cursor 或者等一分钟让它重新索引。

索引出问题的时候：排查清单​

有时候 Cursor 明显"看不见"你的代码。排查清单如下：

1. 检查文件是否被索引​

打开文件，然后问：

我当前在看的是哪个文件？

如果 Cursor 答不上来，这个文件可能不在索引里。

2. 强制重新索引​

命令面板（Ctrl+Shift+P）→ "Cursor: Reindex Codebase"

这会从头重建整个索引。耗点时间，但能解决大多数损坏问题。

3. 查看解析错误​

在 Settings > General > Codebase Indexing 里，检查带红色错误标记的文件。这些文件不会被分析 AST 关系。

常见原因：

  • 文件有语法错误
  • 不支持的编程语言（Cursor 对大约 20 种语言支持较好）
  • 二进制或压缩文件被误识别为源代码

4. 确认 .cursorignore 没有过于激进​

如果你排除了 *.config.*，而你的 vite.config.ts 里包含了重要的路径别名，Cursor 就理解不了你的导入关系。

提升上下文质量​

把正确的文件送进上下文只是第一步。怎么使用这些上下文同样重要。

提问要具体​

不好的：

认证是怎么做的？

好的：

在 @src/auth/middleware.ts 里，JWT 验证是怎么处理过期 token 的？

链式上下文​

如果 Cursor 给了个不完整的回答，用更具体的 @ 引用跟进，而不是重复整个问题。

你提到了限流。@src/middleware/rateLimit.ts —— 限流是怎么计算的？

利用最近打开的文件​

Cursor 在嵌入搜索中会给最近打开的文件更高权重。如果你刚打开了一个文件，@ 引用相关文件时更可能生效，不需要显式提及。

提示

对于复杂的重构，先把所有要改的文件打开一遍。这能"预热"索引，让它们被视为相关。

总结​

  • Cursor 用 嵌入 + AST 来理解你的代码
  • 用 @file、@folder 和 @code: 来显式控制上下文
  • 创建 .cursorignore 排除噪音
  • 感觉不对劲的时候重新索引
  • 提示词要具体——索引负责找文件，但你负责指导怎么用它们

Cursor codebase indexing settings

代码库索引设置面板显示项目的索引状态和任何错误。