很多人碰到过这样的情况：
- 刚装 Cursor，快得飞起
- 用了一个月，@@@ 卡得不行，@按一下按钮要等 3 秒
- 看不了代码补全，切换文件也慢
根本原因：Cursor 的索引（codebase understanding）膨胀了，它在扫描太多不需要的文件。
这篇文章给你：
- 诊断流程：怎么判断"到底是什么拖慢了 Cursor"
- .cursorignore 策略：怎么让 Cursor 只看"有价值"的文件
- 性能恢复方案：缓存、重建、终极方案
结论先说：Cursor 变慢 = 索引膨胀，需要"排除法"
| 症状 | 根因 | 快速修复 |
|---|---|---|
| 打字有延迟、补全慢 | 索引文件太多（包括 node_modules、build） | 加 .cursorignore |
| 搜索代码卡顿 | 文本搜索扫文件时包含了二进制/生成产物 | 排除 dist/、.nuxt/、.output/ |
| @符号跳不出来 | codebase context 窗口超限，开始遗漏文件 | 缩小索引范围，或拆 monorepo |
| 改代码时，Cursor"说不出来"该文件包含哪些接口 | 该文件所在目录的索引坏了 | 删 Cursor cache，重建索引 |
| 要等 20 秒才能看到补全 | 首次索引速度慢（本地硬盘/网络共享） | 用本地 SSD，排除不必要的文件 |
诊断流程：用排除法找到"真凶"
Step 1：查看 Cursor 的索引状态
打开 Cursor：
- Mac：
Cmd + Shift + P→ "Show Cursor Logs" - Win/Linux：
Ctrl + Shift + P→ "Show Cursor Logs"
看日志里有没有这些信息：
[索引进度] 扫描中... 12345 files indexed
[警告] Codebase exceeds recommended size: 50MB (indexed), suggest exclude unnecessary files
[性能] Last completion took 3.2s (slow, recommend optimize)
关键指标：
- Indexed files：应该 < 5000（否则肯定会慢）
- Index size：< 100MB（太大的话开始卡）
- Last completion time：< 500ms（> 1s 说明有问题）
Step 2：列出根目录的"嫌疑文件夹"
大多数项目的"垃圾"都在这几个地方：
node_modules/ ❌ 几千个文件，Cursor 不需要看
dist/, build/, .nuxt/ ❌ 生成产物，不需要看
.output/, .build/ ❌ Nuxt/Next.js 产物
coverage/, __tests__/ ❌ 测试覆盖率和测试文件（除非改测试）
.git/ ❌ Git 历史
Venv/, .venv/, ./env/ ❌ Python 虚拟环境
vendor/ ❌ Composer dependencies
pnpm-lock.yaml, yarn.lock ❌ Lock 文件（太大）
Step 3：建立 .cursorignore 文件
在项目根目录新建 .cursorignore（和 .gitignore 在一起）：
# 依赖与包管理
node_modules/
pnpm-lock.yaml
yarn.lock
package-lock.json
vendor/
# 生成产物
dist/
build/
.output/
.nuxt/
.build/
coverage/
# 开发环境
.env
.env.local
.env.*.local
node/
# VCS 与 IDE
.git/
.github/
.gitignore
.vscode/
.idea/
*.swp
# OS
.DS_Store
Thumbs.db
# 二进制与大文件
*.zip
*.tar.gz
*.exe
*.bin
关键点：
node_modules/一定要排除（这是 90% 的性能问题来源）dist/、.nuxt/、.output/也要排除（生成产物，Cursor 用不上）.git/排除（Git 历史太大了）
Step 4：清除缓存，重建索引
Mac:
rm -rf ~/Library/Application\ Support/Cursor/User/globalStorage/@codeium.codeium
Windows:
rmdir /s /q "%AppData%\Cursor\User\globalStorage\@codeium.codeium"
Linux:
rm -rf ~/.config/Cursor/User/globalStorage/@codeium.codeium
然后重启 Cursor，它会自动重建索引。
实战案例：Monorepo 项目的索引优化
背景：pnpm monorepo，5 个 packages，每个都有 node_modules，总共 800MB。
问题：Cursor 索引了 50000+ 文件，打字延迟 2~3 秒。
诊断：
find . -name "node_modules" | wc -l
# 输出：5（5 个 node_modules）
du -sh node_modules/
# 输出：400MB（根目录的）
du -sh packages/*/node_modules/
# 输出：各 60MB（每个 package 的）
解决方案：
.cursorignore 改成：
# Monorepo 的关键：排除所有 node_modules，只看源码
node_modules/
packages/*/node_modules/
pnpm-lock.yaml
# 生成产物
packages/*/.nuxt/
packages/*/.output/
packages/*/dist/
apps/*/.next/
apps/*/.build/
# 其他
.git/
结果：
- 索引文件数：50000 → 3000
- 打字延迟：2.5s → 100ms
- Cursor 可用性恢复
高级诊断：索引"跑题"的信号
有时候 .cursorignore 设得很对，但 Cursor 还是慢。这说明索引可能"坏了"。
信号 1：Cursor 回答不出"这个文件是什么"
试试：
Cursor chat 里说：@src/components/Button.vue 这个组件的 Props 有哪些？
如果它回答错了或者不知道，说明索引没有正确读取这个文件。
修复：
- 删除该文件所在的缓存：
rm -rf ~/Library/Application\ Support/Cursor/User/... - 重启 Cursor
- 在 chat 里再试一遍
信号 2：按 @ 符号后，列表不完整
在 chat window 里按 @，它应该显示"所有相关文件"。
如果列表里缺少某些文件（比如 stores/ 里的文件都不显示），说明该目录被错误地排除了。
修复：检查 .cursorignore，确保没有误排除。
信号 3：同一个改动，Cursor 在不同时间表现不同
有时候慢，有时候快；有时候生成对，有时候生成错。说明索引不稳定。
修复：
- 关闭 Cursor
- 删除 cache：
rm -rf ~/Library/Application\ Support/Cursor/（注意，这会删除所有 Cursor 配置和 cache，谨慎操作） - 重启，让索引从头开始
Checklist：Cursor 性能优化完整检查表
- .cursorignore 已建立，包含 node_modules/ 和 dist/
- 用 Cursor Logs 确认 indexed files < 5000
- 索引大小 < 100MB
- 打字延迟 < 500ms？
- @ 符号能快速弹出文件列表？
- 关键文件（如 components/、stores/）能被 Cursor 正确识别？
- 尝试改一个小功能，Cursor 生成的代码有没有正确 import？
FAQ
Q：如果是网络共享（SMB/NFS）上的项目，怎么优化？
A：网络共享本身就慢。最好的办法是本地拷一份。如果一定要用网络：
- .cursorignore 要更激进，只对自己改动的目录做索引
- 定期清 cache，重建索引
Q：可以把项目分解成多个 Cursor workspace 吗？
A：不建议。Cursor 本身就支持 monorepo，问题在于索引范围。用 .cursorignore 更灵活。
Q：大文件（如 5MB 的 JSON 数据文件）会拖慢索引吗？
A：会。在 .cursorignore 里加：
*.data.json
*.fixture.json
lib/data/
Q：怎么知道当前是哪个 .cursorignore 在起作用？
A：Cursor Logs 里有一条："Loaded .cursorignore from /path/to/.cursorignore"。
内链
- Cursor 快捷键与工作流：高效开发
- Cursor .cursorrules 模板库：规则配置
- Cursor vs GitHub Copilot vs VS Code：工具选择
- 前端项目 monorepo 架构：项目结构优化
