30 · 代码库索引——Cursor 如何”理解”你的整个项目

Cursor 的 AI 之所以能给出语境精准的回答，核心秘密就是代码库索引（Codebase Indexing）。本文深入剖析索引机制、优化策略与隐私考量。

01 为什么需要代码库索引？

普通的代码编辑器对 AI 的输入方式很简单：你把当前文件发送给模型，模型基于这一个文件的内容来回答。这种方式有两个致命缺陷：

• 单文件视野：AI 看不到项目中其他文件里定义的函数、类型、配置——它只知道你眼前这一小块。
• 缺乏全局语义：即使你把所有文件拼在一起塞给模型，token 窗口也装不下整个大型项目。

Cursor 的解决方案是预先建立代码库索引。在后台，Cursor 把整个项目的代码解析成结构化的语义向量（embedding vectors），存入本地向量数据库。当你在 Chat 或 Agent 中提问时，Cursor 先做语义搜索（semantic search），找到与问题最相关的代码片段，再把它们作为上下文注入到 AI 请求中。

这个流程可以简单理解为：

你提问 → 语义搜索索引 → 找到 Top-K 相关代码块 → 注入 prompt → AI 回答

心智模型：索引就像一本书的详尽索引页——你不需要把整本书塞进脑子，只要知道”这个关键词在第几章第几节”，翻到对应页面就能找到答案。Cursor 的索引不是单按关键词来查的，而是能理解你问的是什么事，哪怕你的描述和代码里的变量名完全不一样。

02 索引机制详解

索引内容

Cursor 默认会对项目中的以下内容建立索引：

索引的粒度是函数/类/代码块级别（chunk-level），而不是文件级别。也就是说，一个 500 行的文件中，Cursor 会把每个函数分别向量化，这样搜索”处理用户登录的函数”能精确定位到 login() 函数，而不是返回整个文件。

索引模型

Cursor 使用专用的 embedding 模型来生成代码片段的向量表示。这不是 OpenAI 或 Anthropic 的通用 embedding——它是专门针对代码语义训练的模型，能够理解编程语言的语法结构和命名惯用法。

其工作原理：

1. 解析 AST：先对每个文件做语法分析（Abstract Syntax Tree），按函数、类、顶级变量切割成块
2. 生成向量：每个代码块通过 embedding 模型转为 1536 维的浮点数向量
3. 存储到向量库：向量和对应的代码块元数据（文件路径、行号范围、语言类型）存入本地 SQLite + vector extension
4. 构建倒排索引：同时保留传统的倒排索引（inverted index），用于关键词精确匹配和正则搜索

这四步的结果就是 Cursor 既能做语义搜索（“帮我找到处理 OAuth 回调的代码”），也能做快速的关键词搜索（“搜索 TOKEN_EXPIRY 常量”）。

03 语义搜索 vs 传统 grep

很多开发者习惯了 grep -r 或 VS Code 的”在文件中搜索”（Cmd+Shift+F）。这两种搜索方式有本质区别：

一个具体的例子。假设你的项目中有这样一个函数：

def revoke_user_token(user_id: int) -> None:
    """Invalidate all active sessions for a given user."""
    redis_client.delete(f"session:{user_id}")
    db.execute("UPDATE tokens SET active = 0 WHERE user_id = ?", (user_id,))

用传统 grep 搜索 用户 登出——无结果，因为代码里没有中文”登出”这个子串。

用 Cursor Chat 问 “用户登出时怎么清除会话的？“——索引匹配到了 revoke_user_token 函数的文档字符串中的 “Invalidate all active sessions” 和代码体中的 redis_client.delete，这些在语义上高度相关，于是返回这个函数作为上下文。

心智模型：传统 grep 是用词的精确拼写来查（字典模式），语义搜索是用词的含义来查（概念模式）。grep 知道 “login” 在哪里，语义搜索知道 “让用户进来这件事” 在哪里，哪怕相关代码的变量名用的是 signIn、authenticate 还是 validateCreds。

04 .cursorignore：精确控制索引范围

不是项目中所有文件都需要被索引。.gitignore 控制哪些文件不进入版本控制，.cursorignore 控制哪些文件不被 Cursor 索引。

配置文件

在项目根目录创建 .cursorignore，语法和 .gitignore 完全一致：

# 忽略构建产物
build/
dist/
out/
.next/

# 忽略依赖目录
node_modules/
vendor/
.venv/
__pycache__/

# 忽略自动生成的文件
*.generated.*
*_pb2.py
*.graphql.ts

# 忽略大文件（超过 100KB 的文件跳过索引以节省性能）
*.onnx
*.pt
*.bin

# 忽略测试输出目录
coverage/
.nyc_output/

# 忽略日志
*.log

# 忽略文档网站构建产物
docs/_build/

推荐的最小配置

对于大多数项目，以下 .cursorignore 是最安全且最有效率的起点：

node_modules
.pnpm-store
.next
dist
build
out
.venv
__pycache__
*.pyc
coverage
.git

为什么不需要忽略所有 node_modules？

你可能想问：为什么 Cursor 不自动忽略 node_modules？实际上它会。Cursor 内置了智能检测——超过一定大小的目录（默认 100MB）或者已知的依赖目录（node_modules、vendor、.venv、包管理器缓存等）会被自动跳过索引。.cursorignore 主要用于那些不是”依赖”但你仍然不希望被索引的目录，比如构建产物、自动生成的代码、包含敏感信息的临时文件。

常见误区

05 索引的性能影响与监控

CPU 与内存占用

索引是一个计算密集型过程。首次打开一个大型项目时，Cursor 会在后台做全量索引：

• CPU：多核利用率 60%—90%，持续 30 秒到几分钟（取决于项目大小）
• 内存：向量数据库额外占用 50—300 MB 内存（按代码量线性增长）
• 磁盘：索引文件存储在 ~/.cursor/index/ 下，每个项目约 10—200 MB

索引完成后，日常运行的增量索引几乎无感——只索引你修改的文件，耗时通常小于 100ms。

索引状态提示

Cursor 在状态栏（右下角）会显示当前索引状态：

建议：首次打开大型项目后，让 Cursor 完整跑完索引再开始使用 AI 功能，否则语义搜索的结果可能不完整。

06 何时需要重新索引？

在以下场景中，Cursor 会自动触发重新索引：

1. 文件创建/删除/重命名：增量更新索引
2. 文件内容变更：修改后 2—3 秒内自动更新对应代码块的向量
3. 项目结构大变动：整体迁移目录结构后触发部分重建
4. Cursor 版本升级：embedding 模型更新后，所有索引向量需要重新生成（这个过程通常在后台静默完成）

手动触发重新索引

如果你觉得 AI 的回答明显遗漏了项目中的关键代码（比如刚加了一大段新功能但 AI 没意识到），可以手动触发：

• 命令面板：Cmd+Shift+P → “Cursor: Rebuild Index”
• 或者在 Cursor 设置中找 Indexing → Rebuild Index

注意：手动重建会清空整个向量数据库并重新索引，大型项目可能需要 1—5 分钟。重建期间 AI 的上下文感知能力会降级到仅基于当前打开文件的内容。

什么时候应该手动重建？

• 你从另一个分支合并了大量代码
• 你发现 AI 持续忽略某个新加的模块或包
• Cursor 升级了大版本，状态栏提示”Index version mismatch”
• 你的 .cursorignore 做了大幅调整

07 大型 Monorepo 策略

对于包含十几个（甚至上百个）子包的大型 monorepo，天真的全量索引会带来显著的性能问题。以下是实战策略：

策略一：按目录隔离索引

在 monorepo 根目录的 .cursorignore 中，明确排除你当前不工作的子包：

# 只索引当前工作的两个包
packages/legacy-api/
packages/shared-lib/**
!packages/shared-lib/src/

# 明确排除不相关的包
packages/mobile-app/
packages/admin-dashboard/
services/*
tools/*

策略二：使用工作区（Multi-root Workspace）

Cursor 支持 VS Code 的 multi-root workspace。如果你把 .code-workspace 文件打开，Cursor 会为每个根目录独立建立索引。你可以创建按功能分组的工作区文件：

{
  "folders": [
    { "name": "api", "path": "packages/api" },
    { "name": "shared", "path": "packages/shared" },
    { "name": "web", "path": "apps/web" }
  ],
  "settings": {
    "cursor.general.indexExcludeFolders": ["**/node_modules", "**/dist"]
  }
}

这样你只加载你需要的几个包，索引的大小和速度都大幅优化。

策略三：基于 @workspace 的意图感知提示

在 Chat 中，如果你只关心某个子目录中的上下文，可以用显式路径提示来引导 AI：

“在 packages/api/src/controllers/ 中，找一下用户注册时发送欢迎邮件的逻辑”

这并不直接影响索引——它影响的是搜索时的范围过滤。语义搜索会结合你的自然语言和隐含的文件路径意图，提高命中率。

一个真实世界的对比

心智模型：Monorepo 索引优化就像给你的 AI 配了一副窄焦眼镜——看得更少，但看得更清。代码库越大，精确聚焦的价值越高。

08 隐私模式与本地索引

什么是隐私模式（Privacy Mode）？

Cursor 的 Privacy Mode 控制的是代码数据是否发送到 Cursor 的服务器。它在两个层面起作用：

重要澄清：很多人误以为索引就是把代码发到 Cursor 的服务器上。实际上，代码索引是全在本地完成的：

1. 代码留在你的磁盘上
2. 向量数据库存储在 ~/.cursor/index/ 中（本地文件）
3. embedding 推理在本地 CPU/GPU 上执行
4. 每次搜索匹配都在本地完成

隐私模式解决的不是”代码是否上传”的问题（索引本身就不上传），而是telemetry 和元数据是否发送给 Cursor 的后端。

如何开启隐私模式

在 Cursor 设置中（Cmd+,）：

Cursor Settings → Privacy Mode → Enable

开启后状态栏会显示 🔒 图标。

本地索引的真实边界

也就是说，索引始终是本地的一闭环境下运行的，隐私模式影响的是 Cursor 自身的遥测行为，而非索引本身的数据流向。

09 Cursor 索引 vs 其他工具的索引

对于需要强隐私保障的团队（金融、医疗、军工），Cursor 的全本地索引方案是目前商业编辑器中最优的选择之一。

10 小结

最佳实践检查清单：

• 项目根目录已有 .cursorignore，排除了 node_modules/dist/build 等目录
• 首次打开大项目后，等索引完成再开始用 AI
• 大型 monorepo 用了 multi-root workspace，而不是直接打开根目录
• 敏感项目的 Privacy Mode 已开启
• 遇到 AI 输出明显遗漏上下文时，尝试重建索引

下一篇：31 Cursor 中的 AI 模型选择与配置 —— 搞清楚不同模型的擅长领域、费用差异，以及如何为每个任务选最合适的模型。