Cursor 会在后台自动为你的代码库建立语义索引，让 Agent 能够理解整个项目的结构和内容——而不只是当前打开的文件。本文介绍索引的工作方式、如何通过 .cursorignore 排除不需要索引的文件、在哪里查看和管理索引状态，以及如何自定义索引加密密钥保护代码安全。

Cursor 代码库索引：让 Agent 理解整个项目

打开 Cursor 开始对话，Agent 不只能看到你当前编辑的文件——它背后有一个持续维护的语义索引，能在整个代码库里搜索相关代码、找到函数定义、理解模块间的关系。

---

索引是怎么工作的

Cursor 在后台自动扫描并索引你的项目文件，建立语义向量数据库。当 Agent 执行"语义搜索"时，查询的就是这个索引。

与关键词搜索的区别：语义搜索理解意思而不只匹配文字。搜索"处理用户登录"能找到名字叫 authenticateRequest 的函数，即使它没有"登录"二字。

---

管理索引：Settings > Indexing

在 Cursor Settings > Indexing & Docs 里可以：

• 查看当前索引状态（正在扫描/已完成/出错）
• 查看被索引的文件列表（View included files）
• 手动触发重新索引

项目文件有大的变动（如切换分支、大规模重构）后，可以手动触发重建确保索引是最新的。

---

排除文件：.cursorignore

如果不想让某些文件被 Agent 索引和访问，在项目根目录创建 .cursorignore，语法与 .gitignore 相同：

# 排除环境变量和密钥文件
.env
.env.*
*.pem
secrets/

# 排除生成文件（大而无意义）
node_modules/
dist/
.next/
build/
coverage/

# 排除大型数据文件
*.csv
*.sql
data/

.cursorignore vs .gitignore 的区别：

	.gitignore	.cursorignore
作用	告诉 Git 忽略哪些文件	告诉 Cursor AI 工具忽略哪些文件
语法	相同	相同
效果	文件不被 Git 追踪	文件不被 Agent 读取和搜索

注意：.cursorignore 只影响 Agent 的工具访问，不影响 Bash 命令（cat .env 仍然可以读取文件）。

---

大型或生成文件的处理建议

以下类型的文件建议加入 .cursorignore，避免浪费索引资源和上下文：

• node_modules/ — 依赖包，内容由包管理器维护
• dist/ build/ .next/ — 构建产物，不需要 Agent 阅读
• *.min.js *.min.css — 压缩后的文件
• 迁移文件 — 数量多且历史数据意义不大
• *.png *.jpg — 图片文件（除非需要视觉分析）
• package-lock.json / pnpm-lock.yaml — 锁文件

---

自定义索引加密密钥

默认情况下，Cursor 的索引数据使用内置加密。如果需要使用自定义加密密钥（企业安全要求），创建 .cursor/keys 文件：

{
  "path_decryption_key": "your-custom-key-here"
}

注意：.cursor/keys 包含密钥，不要提交到 Git。把它加入 .gitignore。

---

常见问题

Q: 代码库很大（10万+ 文件），索引会影响性能吗？

Cursor 索引在后台异步进行，不影响日常编辑操作。但初始索引可能需要几分钟。通过 .cursorignore 排除生成文件和依赖目录可以大幅减少索引量。

Q: Agent 搜索不到某个文件里的内容，怎么排查？

检查该文件是否在 .cursorignore 或 .gitignore 里；在 Settings > Indexing > View included files 确认文件是否在索引中；如果不确定，可以直接用 @文件名 引用它，绕开搜索直接添加到上下文。

Q: 切换 Git 分支后，索引会自动更新吗？

会，Cursor 监听工作区变化并自动重索引。如果发现搜索结果还是旧分支的内容，可以在 Settings > Indexing 手动触发重建。