cursor-codebase-indexing

Cursor 代码库索引

概述

配置代码库索引，让相关源代码和文档可供使用，同时将敏感、生成的、超大的及无关文件排除在 AI 上下文之外。

前置条件

• 确认仓库所有权、预期的源代码和文档路径，以及经过审核的 .cursorignore/索引排除项。
• 准备一个非敏感的验证样例，以及配置更新的变更审核流程。

说明

1. 明确预期的工作区范围，并在首次索引前添加排除项。
2. 验证必需文件可以被找到，并确认排除的路径无法附加或发现。
3. 仅在审核过配置或工作区变更后重新索引，并记录脱敏后的结果。
4. 监控索引大小和性能；应缩小范围，而不是放宽数据控制。

输出

• 经过验证的索引范围，明确列出包含/排除路径，并指定维护负责人。

示例

为某个服务索引 src/ 和 docs/，同时排除 .env*、构建输出、供应商目录和客户数据导出文件。在允许 AI 处理该仓库之前，验证经过脱敏的源文件可用，并确认被排除的占位文件不可用。

设置并优化 Cursor 的代码库索引系统。索引会为代码创建嵌入向量，从而支持 @Codebase 语义搜索，并提升 Chat、Composer 和 Agent 模式下的 AI 上下文感知能力。

索引的工作原理

Your Code Files
      │
      ▼
  Syntax Chunking ─── splits files into meaningful code blocks
      │
      ▼
  Embedding Generation ─── converts chunks to vector representations
      │
      ▼
  Vector Storage (Turbopuffer) ─── cloud-hosted nearest-neighbor search
      │
      ▼
  @Codebase Query ─── your question → embedding → similarity search → relevant chunks

关键架构细节

• Merkle 树用于检测变更：仅重新索引已修改的文件（每 10 分钟一次）
• 不存储明文：代码不会存储在服务器端；仅存储嵌入向量和经过混淆的元数据
• 兼容隐私模式：开启隐私模式后，计算嵌入向量时不会保留源代码
• 索引在后台运行；小型项目可在数秒内完成，大型项目（50K+ 个文件）首次索引可能需要数小时

初始设置

1. 在 Cursor 中打开项目
2. 首次打开时会自动开始索引
3. 检查状态：查看底部状态栏中的“正在索引……”指示器
4. 查看已索引文件：Cursor Settings > Features > Codebase Indexing > View included files

验证索引状态

状态栏显示：

• **“正在索引……”**并显示进度指示器 —— 正在进行初始索引
• “已索引” —— 索引完成，@Codebase 查询可用
• 没有指示器 —— 索引可能已禁用或尚未启动

配置

.cursorignore

将文件排除在索引和 AI 功能之外。在项目根目录中创建该文件。使用 .gitignore 语法：

# .cursorignore

# Build artifacts (large, not useful for AI context)
dist/
build/
out/
.next/
target/

# Dependencies
node_modules/
vendor/
venv/
.venv/

# Generated files
*.min.js
*.min.css
*.bundle.js
*.map
*.lock

# Large data files
*.csv
*.sql
*.sqlite
*.parquet
fixtures/
seed-data/

# Secrets (defense in depth -- also use .gitignore)
.env*
**/secrets/
**/credentials/

.cursorindexingignore

仅将文件排除在索引之外；显式引用时，AI 功能仍可访问这些文件：

# .cursorindexingignore

# Large test fixtures -- don't index, but allow @Files reference
tests/fixtures/
e2e/recordings/

# Documentation build output
docs/.vitepress/dist/

区别： .cursorignore 会让索引和 AI 功能都无法访问文件。.cursorindexingignore 只会将文件排除在索引之外；仍可通过 @Files 引用这些文件。

默认排除项

Cursor 会自动排除 .gitignore 中的所有内容。只有当你想将 Git 跟踪的文件排除在 AI 之外时，才需要使用 .cursorignore。

使用索引

@Codebase 查询

针对整个代码库提出语义问题：

@Codebase where is user authentication handled?

@Codebase show me all API endpoints that accept file uploads

@Codebase how does the payment processing flow work?

@Codebase find all places where we connect to Redis

@Codebase 会使用你问题的嵌入向量进行最近邻搜索。它会返回语义最相似的代码片段，即使这些片段不包含你使用的确切关键词。

@Codebase 与 @Files 和文本搜索的比较

方法	适用场景	上下文开销
@Codebase	探索 —— 不知道有哪些文件	高（许多片段）
@Files	明确知道具体文件	低（一个文件）
@Folders	知道目录	中到高
Ctrl+Shift+F	精确文本/正则表达式匹配	不适用（编辑器搜索）

使用 @Codebase 进行探索；确定代码所在位置后，再切换到 @Files。

大型项目优化

Monorepo 策略

对于包含许多软件包的 monorepo，请打开特定的软件包目录，而不是根目录：

# Instead of opening the entire monorepo:
cursor /path/to/monorepo           # Indexes everything -- slow

# Open the specific package:
cursor /path/to/monorepo/packages/api   # Indexes only this package -- fast

也可以在根目录使用 .cursorignore，排除当前没有处理的软件包：

# .cursorignore -- monorepo, focus on api and shared
packages/web/
packages/mobile/
packages/admin/
# packages/api/    ← not listed, so it IS indexed
# packages/shared/ ← not listed, so it IS indexed

重新索引

如果搜索结果已过时，或索引似乎卡住：

1. Cmd+Shift+P > Cursor: Resync Index
2. 等待状态栏显示索引进度
3. 如果仍未解决，请删除本地缓存：
   • macOS：~/Library/Application Support/Cursor/Cache/
   • Linux：~/.config/Cursor/Cache/
   • Windows：%APPDATA%\Cursor\Cache\
4. 重启 Cursor，并等待完成完整重新索引

文件监视器限制（Linux）

在 Linux 上，大型项目可能会触及文件监视器限制：

# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# Increase (temporary)
sudo sysctl fs.inotify.max_user_watches=524288

# Increase (permanent)
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

企业注意事项

• 数据驻留：嵌入向量存储在 Turbopuffer（云端）。文件名经过混淆，不包含明文代码，但仍会保留元数据
• 隐私模式：启用隐私模式后，嵌入向量会由提供商在零数据保留的情况下计算
• 隔离网络环境：索引需要联网访问 Cursor 的嵌入 API。离线时不可用
• 索引范围：仅对当前打开的工作区中的文件建立索引。关闭项目后，其索引将不再用于活动查询

故障排除

症状	原因	解决方法
@Codebase 没有返回结果	尚未建立索引	等待状态栏显示“Indexed”
搜索未找到已知文件	文件位于 .gitignore 或 .cursorignore 中	检查忽略文件
索引停留在 N%	项目过大或网络问题	通过命令面板重新同步索引
重构后结果过时	索引尚未更新	等待 10 分钟或手动重新同步
索引期间 CPU 占用率高	正在计算初始嵌入向量	首次运行时属正常现象，之后会降低

资源

• 代码库索引文档
• 忽略文件
• 安全的代码库索引