Cursor 陷阱合集

Cursor 用过的都知道，它强但也有独特的坑。8 个真实踩坑场景，症状 / 根因 / 出坑 / 预防四段式展开。

踩过新坑？提 Issue 或 PR。

陷阱 1：Composer 脱缰 — 动了你没让它动的文件

症状

用 Composer 改一个功能，结果 diff 涉及 6 个文件
有些文件你都没打开过，它跨目录找到然后顺手改了
最糟：它"重构"了 src/utils/ 某个公共工具，破坏了别的功能

根因 Composer 是 Agent 模式，默认有权限跨文件修改。它会自己搜索相关文件、自己决定"这个也得改"。没有显式边界时，"相关"的定义由它说了算。

出坑

停。把所有非 [我指定的文件] 的改动回滚。
只保留 @src/pages/order/list.tsx 这个文件的改动。

预防 Composer 提示词里显式圈定范围：

用 Composer。只改这两个文件：
@src/pages/order/list.tsx @src/pages/order/detail.tsx

如果需要改其他文件才能完成，先告诉我，让我决定。

或者在 .cursor/rules/ 里加：

## Composer 边界
- 除非我 @ 引用了某文件，不要修改它
- src/utils/ src/types/ 目录属于公共代码，改动前必须告知

陷阱 2：Tab 补全一次吐一整页，Esc 来不及按

症状

你只想写一个变量名，Tab 一按补出来 30 行代码
补全的代码看起来 OK 但实际有隐蔽的 bug（比如硬编码数据、错误的类型假设）
养成"反手 Undo"习惯后，开发反而变慢

根因 Cursor 的 Tab 补全会预测"你接下来想写的一整段"，不是单行补全。遇到函数开头、文件开头这种"信息密集点"，它会直接补出完整函数体。

出坑

长补全按 Esc 直接拒绝
已经接受了不对：Cmd+Z 撤销，或用 Cmd+K 选中这段问"这段有什么问题"

预防

Cursor Settings → Features → 调低补全长度（或关闭 Auto 模式改成只补全当前行）
写函数签名和类型再等补全——签名越完整，补全越准（反之越瞎猜）
重要逻辑块先写一行注释再等补全：

// 计算两个日期之间的工作日，排除周末和中国法定节假日
function countBusinessDays(start: Date, end: Date): number {
  // Tab 补全会基于注释生成正确实现
}

陷阱 3：`.cursorrules` 太长，规则全没生效

症状

花半天写了 300 行 .cursorrules，覆盖各种场景
实际用起来：AI 该违反的还是违反，感觉根本没读
新加的规则像"扔进黑洞"

根因 .cursorrules 单文件超过 ~200 行时，靠后的规则被边缘化——Cursor 会对长文件做"摘要注入"，细节条款被丢弃。

出坑拆到 .cursor/rules/（注意是目录，不是单文件）：

.cursor/rules/
├── global.md           # 无条件加载的核心规则（< 100 行）
├── react.md            # 仅 .tsx 文件触发
├── api.md              # 仅 src/api/ 下触发
└── testing.md          # 仅 *.test.ts 触发

每个文件加 frontmatter 控制加载：

---
globs: ["src/components/**/*.tsx"]
---

# React 组件规则
- Props 必须用 interface 定义
- 必须处理 loading 和 error 状态

预防

新项目一开始就用 .cursor/rules/ 目录，别用单文件 .cursorrules
每个规则文件控制在 100 行内
规则太具体、太场景化的，放 Notepad，用到再 @ 引用

陷阱 4：`@file` 引用失效 — 上下文没真传进去

症状

你说 @src/types/user.ts 按这个类型改接口
AI 生成的代码里的字段名、类型全是它猜的，不是你的真实类型
仔细看会发现：它根本没读那个文件

根因常见原因三种：

路径错了（大小写 / 相对绝对）
文件超大被截断（只读了前 N 行）
你文件刚改过还没存盘（Cursor 读的是磁盘版本）

出坑

先确认：@src/types/user.ts 这个文件里 User 接口的字段名都是什么？
列出来我对一下，再开始改代码。

让 AI 先复述文件内容，确认它真的读到了，再让它动手。

预防

大文件用 @folder 引用整个目录让它自己找，比 @file 精确到路径稳
改完文件先 Cmd+S 存盘再 @ 引用
超大文件（>1000 行）精确引用行号范围：@src/models/big.ts:50-120

陷阱 5：Chat vs Composer 混用，效率全失

症状

在 Chat 里问"帮我重构这个模块"——它给你一大堆建议文字，不改代码
在 Composer 里问"这段代码怎么理解"——它不回答，直接开始改
你来回切换，每次都选错模式

根因

Chat (Cmd+L)：问答模式，不主动改代码
Composer (Cmd+I)：Agent 模式，优先改代码
Inline (Cmd+K)：行内编辑，只改选中区域

三个模式的触发入口不一样，新手分不清。

出坑切错模式了：把任务内容复制，关闭当前面板，打开正确模式粘进去。

预防记住快捷键和用途的一一对应：

你想做什么	用哪个	快捷键
问问题、理解代码	Chat	`Cmd+L`
改选中的一段代码	Inline	`Cmd+K`
跨文件大改动	Composer	`Cmd+I`

陷阱 6：模型切换导致风格不一致

症状

你在 Cursor 里一半时间用 Claude 3.5，一半用 cursor-small
同一个项目里代码风格分裂：有的地方严谨地写类型，有的地方随意 any
你自己都没意识到是模型切换导致的

根因 Cursor 支持多模型，不同模型的"默认风格"不同：

Claude Sonnet：倾向严谨，会主动加类型、加错误处理
GPT-4：倾向简洁，少废话少注释
cursor-small：速度快，但在复杂任务上会偷懒

自动切换（系统根据任务复杂度选模型）会让这个问题更隐蔽。

出坑把风格规则写进 .cursor/rules/global.md，不管用哪个模型都会遵守：

# 代码风格（跨模型一致）
- 必须用 TypeScript，不用 any
- 函数必须有返回值类型标注
- 错误用 Result<T, Error> 包装，不抛异常

预防

一个项目定一个主模型，在设置里锁定
明确任务才换模型（"这个任务用 Opus 深度思考"）
不要依赖 auto 选模型

陷阱 7：Notepads 上下文污染

症状

半年前建的 Notepad 里有过时信息（旧 API 设计、废弃的代码风格）
新对话里 AI 引用 Notepad，给出了过时方案
你都不记得自己建过这个 Notepad

根因 Notepads 是手动管理的上下文片段，Cursor 不会自动更新它。项目演进几个月后，Notepads 和真实代码就开始脱节。

出坑

定期清理：看到 AI 用了奇怪方案，怀疑是 Notepad 污染，去 Notepad 面板检查
发现过时内容立刻删除或更新

预防

Notepad 只放稳定的约定（API 返回格式、认证方式等不常变的）
易变的内容（当前正在做的功能、临时方案）用 @folder 引用实时代码而不是 Notepad
Notepad 里加修改日期，定期检查："2026-01 以前的都复审一次"

陷阱 8：索引过期 — @ 引用到已删除的文件

症状

你重命名或删除了某个文件
在 Chat 里 @ 还能引用到它（带着旧内容）
AI 基于旧文件给建议，你按建议改，编译报错"文件不存在"

根因 Cursor 的代码库索引不是实时更新。删除/重命名后，内存里的索引还保留旧条目一段时间。

出坑命令面板（Cmd+Shift+P）→ Cursor: Resync Index

预防

大规模重命名/删除后主动重建索引
如果用 Git 分支切换频繁，切分支后跑一次 resync
发现 @ 引用结果奇怪，第一反应先检查索引，不要怀疑 AI

贡献新陷阱

模板见 claude-code.md 结尾。

AI 编程实战三卷书