Cursor进阶教程：从代码补全到全项目重构的实战指南

如果你已经会用 Cursor 基础教程 里的 Tab 补全、Cmd+K 修改选中代码，但总觉得"Cursor 能做的应该不止这些"——这篇就是为你写的。

Cursor 真正的杀手锏不是"它能补全代码"——而是 5 个大部分人没真正用起来的能力：Cmd+K 行内重构（选中即改整个函数）、@codebase 项目上下文（理解整个代码库而不是单个文件）、Agent 模式多文件自主开发（描述目标 AI 跑完整个任务）、Cursor Rules 团队规范固化（让 AI 永远按你的代码风格写）、Composer 多文件协同编辑（一次改 5 个文件保持一致）。这 5 个功能如果你都不会用，Cursor 在你手里就是个"会补全的 VS Code"；如果你都玩明白，它就是2026 年最强的 AI 编程环境——没有之一。

这篇不讲注册（参考 Cursor 基础教程 和 Trae 教程），直接讲进阶玩法。读完你能在 30 分钟内把这 5 个功能全开起来。

1. Cmd+K 行内重构 — 选中即改整个函数

最容易被低估的能力。很多人以为 Cmd+K 就是"让 AI 改几行代码"——但真正用起来你会发现：Cmd+K 可以一次重构整个函数、改变量命名、提取公共逻辑、加错误处理、加单元测试。这是 Cursor 区别于普通 AI 聊天工具的核心。

打开任意代码文件，选中一段代码（函数、类、几行表达式都行），按 Cmd+K（Windows/Linux 是 Ctrl+K），右侧弹出输入框——输入你的修改指令。

怎么用

1. 选中目标代码（一个函数、一个类、几行表达式都可以）
2. 按 Cmd+K 弹出输入框
3. 不要输入"优化这段代码"这种模糊指令，而是指定具体动作：

把这函数改成 async/await，去掉 callback 嵌套

给这个函数加 TypeScript 类型注解，参数和返回值都要

把这 React 组件从 class 改成 hooks，并加 useMemo 优化

给这 3 个函数加 Jest 单元测试，覆盖正常 + 异常分支

1. Cursor 会给出 diff（红删绿增），按 Cmd+Enter 接受，Cmd+Z 撤销

我的实战场景（重构遗留代码）

我接手过一个 5 年前写的 Node.js 项目，500+ 个文件全是 callback 嵌套，没有 TypeScript，没有测试。传统方式：手动重构 = 3 周。

用 Cursor Cmd+K：

// 选中 200 行的 callback 嵌套函数
把这函数改成 async/await 模式，保持外部 API 不变
// Cmd+Enter 接受
// 然后选中整个文件
给这文件加 TypeScript 类型注解
// 再选中所有函数
给所有公开函数加 JSDoc 注释

单文件 5 分钟搞定，500 个文件分批处理（每次 10 个）= 2 周完成 + 质量提升。

注意事项

⚠️ Cmd+K ≠ 万能重构工具：

• 复杂业务逻辑的重构，AI 可能改错逻辑（必须人工 review）
• 跨文件依赖的重构，Cmd+K 看不到全局（用 @codebase 或 Agent）
• 大型函数（>500 行）AI 重构可能丢失上下文，建议先拆函数再重构
• 最佳实践：小改动（小于 50 行）用 Cmd+K / 中等改动用 Composer / 大改动用 Agent

2. @codebase 项目上下文 — 理解整个代码库而不是单个文件

最被忽视的能力。Cursor 真正的杀手锏是它能索引你的整个项目——这意味着你问它"我们项目里有没有用 X 库"时，它会真的搜遍所有文件而不是凭记忆瞎猜。这是 Cursor 区别于 ChatGPT / Claude 网页版的本质差异。

在 Cursor 的 Chat 面板（Cmd+L）输入 @codebase 或者直接问问题，Cursor 会自动索引项目所有文件后回答。

怎么用

1. 打开 Cursor Chat 面板（Cmd+L 或 Cmd+I）
2. 输入 @codebase 触发项目上下文，或者直接问：

@codebase 我们项目里哪些地方用了 redux-saga？

@codebase 请找出所有调用 userService.getUser() 的地方，列出文件路径

@codebase 我们项目用的是什么 ORM？配置文件在哪里？

@codebase 帮我理解这个项目：入口文件、路由结构、数据流、主要模块

1. Cursor 会真的搜遍项目所有文件（默认索引 .gitignore 内的所有内容），给出精准答案和文件路径
2. 快捷符号：
   • @file - 单个文件上下文
   • @folder - 整个文件夹
   • @docs - 官方文档（Cursor 帮你搜官方文档）
   • @web - 联网搜索
   • @git - 当前 git diff

我的实战场景（快速熟悉新项目）

我每周要评估 2-3 个开源项目（看是否值得集成）。传统方式：手动看 README + 入口文件 + 主要目录 = 30 分钟起步。

用 Cursor @codebase：

@codebase 这个项目的：
1. 主要功能是什么？（用 3 句话总结）
2. 技术栈是什么？（语言、框架、数据库）
3. 入口文件在哪里？启动命令是什么？
4. 路由结构是怎样的？
5. 主要业务模块有哪几个？各自职责？
6. 哪些文件是核心（修改最多的）？

5 分钟拿到完整项目地图，比手动看快 6 倍。

注意事项

⚠️ @codebase ≠ 全知全能：

• 大型项目（>10万行）首次索引需要 1-2 分钟
• 二进制文件、生成的代码、node_modules 等默认不索引（可配置）
• @codebase 看的是当前 git 状态，未提交的修改也可能被忽略
• 提问要具体，避免"这个项目好不好"这种主观问题
• 最佳实践：先 @codebase 项目结构 拿地图 → 再针对具体模块问细节

3. Agent 模式 — 描述目标，AI 自主完成多文件开发

最被高估但又最被低估的能力。很多人听说 Cursor 有 Agent 模式，但用起来发现"AI 跑偏了"就放弃了——这是因为不会用。Agent 模式的正确打开方式是：给具体目标 + 给明确边界 + 分步 review。

按 Cmd+I 打开 Composer/Agent 面板，输入目标描述，Agent 会自主规划、读文件、编辑代码、跑命令、检查错误、修复、再跑——直到任务完成。

怎么用

1. 按 Cmd+I 打开 Agent 面板
2. 输入具体且有边界的目标：

// ✅ 好的目标描述
给 src/api/ 目录下所有 Express 路由加 rate limit 中间件：
1. 引入 express-rate-limit
2. 默认 100 次/分钟/IP
3. /api/auth/login 限 10 次/分钟（防爆破）
4. 保持原有错误响应格式
5. 跑 npm test 确保测试通过

// ❌ 模糊的目标描述
优化一下 API 代码

1. Agent 会列出执行计划（计划读哪些文件、改哪些代码、跑哪些命令）
2. 每一步都 review：Agent 会询问"是否继续？"时，确认无误再继续
3. 关键技巧：
   • "先只读不写，列出修改清单" → 让 AI 先分析
   • "改完跑测试" → 让 AI 验证
   • "保持原有的错误处理风格" → 避免 AI 改坏
   • "修改前先 git checkout 创建分支" → 安全第一

我的实战场景（添加新功能模块）

我需要给一个 Next.js 项目加"用户书签"功能（5 个文件、3 个 API、2 个组件）。传统方式：手动写 = 2-3 小时。

用 Cursor Agent：

给项目加"用户书签"功能：
1. 数据库：在 prisma/schema.prisma 加 Bookmark model（userId, itemId, createdAt）
2. API：创建 /app/api/favorites/route.ts（GET 列表、POST 添加、DELETE 取消）
3. 组件：创建 <FavoriteButton /> 组件，放在 /components/
4. 页面：在 /app/items/[id]/page.tsx 集成 FavoriteButton
5. 测试：跑 npm run test 确保全部通过
6. 跑 npm run build 确保构建成功

Agent 跑了 8 分钟，自主完成了 5 个文件的创建/修改 + 测试 + 构建检查。我 review 了所有 diff，发现 2 个边界情况 bug，让 Agent 修复后又跑了 3 分钟。总计 11 分钟。

注意事项

⚠️ Agent ≠ 替代人工 review：

• Agent 可能改错（特别是复杂业务逻辑），必须 review 每个 diff
• Agent 可能引入新 bug（破坏原有功能），必须跑测试
• Agent 可能过度修改（改了你没要求的东西），必须看 git diff
• Agent 在大型项目上可能很慢（10+ 分钟），建议分小任务
• 最佳实践：小任务（小于 10 文件）直接 Agent / 中任务（10-30 文件）拆 2-3 个 Agent 调用 / 大任务（大于 30 文件）手动分阶段

4. Cursor Rules — 团队规范固化，让 AI 永远按你的代码风格写

最专业的功能。这是 Cursor 在 2025 年推出后最有价值的更新——通过 .cursorrules 文件，你可以让 Cursor 永远按你团队的代码风格、命名规范、技术选型来生成代码。新员工入职不需要再培训代码风格，AI 帮你统一。

在项目根目录创建 .cursorrules 文件（纯文本），写你的规则，Cursor 会在每次生成代码时自动应用这些规则。

怎么用

1. 在项目根目录创建 .cursorrules（无扩展名的纯文本）
2. 写规则（每行一条，支持注释）：

# 项目：电商后台管理系统
# 技术栈：Next.js 14 + TypeScript + Prisma + PostgreSQL

## 命名规范
- React 组件：PascalCase（UserProfile.tsx）
- 工具函数：camelCase（formatDate.ts）
- 常量：UPPER_SNAKE_CASE（API_BASE_URL）
- 数据库字段：snake_case（user_id, created_at）
- API 路由：kebab-case（/api/user-profile）

## 代码风格
- 优先用函数组件，不要 class 组件
- 优先用 server components（标记 'use client' 只在必要时）
- TypeScript 严格模式，禁止 any
- 错误处理用 try/catch + 自定义错误类（AppError）
- API 响应格式统一：{ success: boolean, data?: T, error?: { code, message } }

## 禁止
- 不要用 console.log，用 logger（pino）
- 不要硬编码配置，用环境变量
- 不要写 // TODO 注释，要写 // FIXME-[日期]-[原因]
- 不要用 moment，用 date-fns
- 不要用 Redux，用 Zustand

1. Cursor 在生成代码时自动应用这些规则（不需要手动指定）
2. Cursor Rules 是项目级的——和代码一起 commit，新成员 clone 项目后自动生效

我的实战场景（团队 5 人协作）

我带的 5 人前端团队，每周要 review 30+ 个 PR。以前最大的痛点是代码风格不一致——有人用 2 空格缩进，有人用 4 空格；有人用单引号，有人用双引号。每次 review 都要花 20% 时间纠结风格问题。

引入 .cursorrules 后：

• AI 生成的代码自动符合团队规范
• 风格 PR 减少 80%（review 速度快 30%）
• 新员工上手时间从 1 周缩到 2 天（AI 帮他们按规范写代码）
• 代码审查从"挑风格"变成"挑逻辑"，PR 通过率从 60% 提升到 85%

注意事项

⚠️ Cursor Rules ≠ 银弹：

• 规则太多（>100 条）AI 反而无所适从，建议控制在 30-50 条
• 规则要具体，避免"写好代码"这种空话
• 规则要定期 review，项目演进时更新规则
• 规则是建议性的，不是强制约束（AI 可能违反，需要人工 review）
• 最佳实践：从最重要的 10 条开始 → 团队 review 1 个月 → 逐步加到 30-50 条

5. Composer 多文件协同编辑 — 一次改 5 个文件保持一致

最被低估的多文件能力。很多人不知道 Cursor 的 Composer 模式可以同时编辑多个文件——比如改 API 路由时，自动同步更新前端调用、TypeScript 类型、测试用例、文档。这是 Cursor 区别于其他 AI 编程工具的最大优势。

按 Cmd+I 打开 Composer 模式（不是 Agent 模式），输入跨文件的修改需求，Composer 会列出所有要修改的文件 + diff，一次性确认。

怎么用

1. 按 Cmd+I 打开 Composer 面板
2. 在右上角切换到 Composer 模式（不是 Agent 模式）
3. 输入跨文件的修改需求：

// ✅ 跨文件修改
把项目里所有 "userId" 改成 "userId" → 实际是统一用 "user_id"

把 API /api/users/[id] 的返回字段从 { id, name, email } 改成 { id, name, email, avatarUrl }，并更新：
1. 前端所有调用这个 API 的地方（src/components/User*.tsx）
2. TypeScript 类型定义（src/types/user.ts）
3. 测试用例（tests/api/users.test.ts）
4. API 文档（docs/api.md）

1. Composer 列出所有要修改的文件和 diff
2. 一次确认 = 所有文件同步修改
3. 关键技巧：
   • 用 "// 改完跑测试 + 检查类型" 让 Composer 自动验证
   • 用 "保持原有错误处理" 避免改坏
   • 用 "修改前先 git diff 看一下" 知道基线

我的实战场景（API 重构）

我需要把 20 个 API 路由的响应格式从 { data, error } 改成 { success, data, error }，同步更新 50+ 个前端调用点。传统方式：手动改 70 个文件 = 半天。

用 Cursor Composer：

把所有 API 路由的响应格式从：
{ data: T, error?: string }
改成：
{ success: boolean, data?: T, error?: { code, message } }

并同步更新：
1. 所有前端 fetch 调用点（src/**/api/*.ts）
2. TypeScript 类型定义（src/types/api.ts）
3. 测试用例（tests/api/*.test.ts）
4. 错误处理工具函数（src/utils/error.ts）
5. API 文档（docs/api/*.md）
6. 跑 npm test 确保通过

Composer 跑了 6 分钟，修改了 67 个文件。人工 review 关键 10 个文件，发现 1 处需要调整，让 Composer 修了 30 秒。总计 7 分钟 vs 半天。

注意事项

⚠️ Composer ≠ 无脑信任：

• 跨文件修改的风险高于单文件，必须 review 所有 diff
• Composer 可能改了你不希望改的地方（必须用 git diff 仔细看）
• 复杂业务逻辑的同步修改，Composer 可能漏掉边界情况
• Composer 在大型项目上很慢，建议分批处理（一次 5-10 个文件）
• 最佳实践：先 git commit 当前状态 → Composer 改 → 跑测试 → review diff → 决定是否回滚

6. 不适合 Cursor 高级功能的场景

这 5 个功能不是万能的，以下场景建议换其他工具：

如果你要做的内容涉及纯数据科学、离线开发、移动端原生开发——Cursor 不是首选。但对于绝大多数 Web 开发、脚本编写、API 开发、自动化任务，Cursor 仍然是 2026 年最强 AI 编程环境。

7. 30 分钟上手清单

今天就能把这 5 个功能全开起来：

• 分钟 0-5：测试 Cmd+K 重构 → 打开任意代码文件 → 选中一个函数 → Cmd+K → 输入"给这函数加 TypeScript 类型"
• 分钟 5-10：测试 @codebase → Cmd+L 打开 Chat → 输入"@codebase 这个项目的主要模块有哪些？"
• 分钟 10-15：测试 Agent 模式 → Cmd+I → 输入"给 src/utils.ts 加一个 debounce 函数并写测试" → review diff
• 分钟 15-20：创建 .cursorrules → 项目根目录创建 .cursorrules → 写 10 条最重要的规则
• 分钟 20-25：测试 Composer → Cmd+I 切到 Composer → 输入"把所有 console.log 改成 logger.info"
• 分钟 25-30：完整跑一遍 → 选个真实任务 → 用 Agent 或 Composer 完成 → 跑测试 → review diff

完成后你就拥有了：行内 AI 重构 + 项目级代码理解 + Agent 多文件开发 + 团队规范固化 + 多文件协同编辑——这是 Cursor 老玩家和普通用户的分水岭。

下一步

1. 想用免费替代？ 看 Trae 教程——字节出品的免费 AI IDE，新手友好
2. 想对比其他 AI 编程工具？ 看 AI 编程工具推荐——GitHub Copilot / Cursor / Trae / Cody 横评
3. 想用 Claude 写代码？ 看 Claude 进阶教程——Claude 在代码推理场景比 Cursor 后端模型更准
4. 想用 DeepSeek 写代码？ 看 DeepSeek 进阶教程——DeepSeek V3 在中文代码场景免费且强
5. 想批量自动化开发？ 看 AI 写代码实战——AI 写代码的 5 个真实工作流

如果你已经把这 5 个功能玩明白了，下一步建议是给团队配一套 Cursor Rules——把代码风格、命名规范、技术选型固化到 .cursorrules，让 AI 帮整个团队统一代码质量。这就是从"用 AI 写代码"到"用 AI 武装团队"的转变。