Cursor AI 编程终极指南：从入门到 Agent 模式的完整教程

Cursor 不只是代码补全

用了 Cursor 半年，我发现大多数人只用到了它 20% 的能力。

他们知道 Tab 补全，知道 Cmd+K 可以生成代码，知道 @ 可以引用文件。但这些只是 Cursor 的"入门三件套"。

真正让 Cursor 成为效率杀手锏的，是 Agent 模式、自定义规则系统、多文件编辑和 MCP 集成。这些功能组合起来，能让一个中级程序员达到高级工程师的产出。

这篇指南会带你从基础到精通，覆盖 Cursor 的每一个高价值功能。

核心概念：Cursor 的三种模式

Cursor 有三种核心交互模式，理解它们的区别是高效使用的基础：

补全模式（Tab）：打字时自动建议，按 Tab 接受。适合逐行编码。

编辑模式（Cmd+K）：选中代码，描述修改意图，Cursor 生成差异化编辑。适合精确修改。

Agent 模式（Cmd+I）：给 Cursor 一个目标，它会自主规划、搜索代码库、编辑多个文件、运行终端命令。适合复杂任务。

简单度：Tab > Cmd+K > Agent
能力值：Tab < Cmd+K < Agent

新手常见错误：用 Agent 模式做简单的事（浪费 Token），用 Tab 做复杂的事（做不到）。

Tab 补全的隐藏技巧

Tab 补全看似简单，但有几个隐藏技巧：

1. 多行补全：Cursor 会根据上下文预测你需要写多行代码，不要急着按 Tab，等它生成完整。

2. 部分接受：如果你只需要补全建议的一部分，可以用 Cmd+→ 逐词接受。

3. 查看替代建议：按 Option+] 可以在多个补全建议之间切换。

4. 补全预测方向：Cursor 会根据你最近编辑的文件和函数来预测你需要什么。保持良好的文件组织结构，补全质量会显著提高。

Cmd+K 编辑的艺术

Cmd+K 是日常使用频率最高的功能。关键在于如何写好 Prompt。

差的 Prompt：

修复这个 bug

好的 Prompt：

这个函数在传入空数组时返回 undefined 而不是 []。
添加空值检查，确保总是返回数组。
同时添加 TypeScript 类型守卫。

好 Prompt 的公式：问题 + 期望行为 + 额外要求

高级用法——链式编辑：

你可以连续使用 Cmd+K，让 Cursor 逐步完成复杂修改：

第一步：选中接口定义 → "添加 pagination 参数"
第二步：选中实现函数 → "根据新增的 pagination 参数实现分页逻辑"
第三步：选中调用处 → "更新调用代码，传入正确的分页参数"

Cursor 会记住你的编辑上下文，后续步骤会理解前序修改。

Agent 模式：Cursor 的杀手锏

Agent 模式是 Cursor 与其他 AI 编辑器拉开差距的核心功能。

在 Agent 模式下，Cursor 会：

1. 分析你的需求
2. 自动搜索相关代码文件
3. 规划编辑步骤
4. 执行多文件编辑
5. 运行终端命令（安装依赖、运行测试）
6. 根据执行结果自我修正

使用快捷键：Cmd+I（Mac）/ Ctrl+I（Windows/Linux）

最佳实践——写好 Agent Prompt：

## 任务：给用户管理模块添加批量导入功能

### 需求：
1. 支持从 CSV 文件导入用户
2. 导入前验证数据格式（邮箱、手机号）
3. 显示导入进度条
4. 生成导入结果报告（成功数、失败数、失败原因）
5. 支持断点续传

### 技术要求：
- 后端使用现有的 UserService
- 前端使用已有的 Upload 组件
- 遵循项目现有的错误处理模式
- 写单元测试

给 Agent 足够的上下文，它就能一次性完成复杂任务。

Agent 模式的边界：

• 大型重构（超过 20 个文件）——拆成多个小任务
• 需要理解复杂业务逻辑——先用 Chat 模式讨论方案
• 涉及数据库迁移——手动确认 SQL 后再执行

自定义规则：让 Cursor 懂你的项目

Cursor 的 .cursorrules 文件（现在推荐用 .cursor/rules/ 目录）是你让 Cursor 理解项目约定的方式。

新版规则系统（.cursor/rules/）：

# .cursor/rules/typescript.md

## 代码风格
- 使用函数式组件 + hooks
- 状态管理用 Zustand，不用 Redux
- 样式用 Tailwind CSS
- API 请求用 React Query

## 命名规范
- 组件文件用 PascalCase: UserProfile.tsx
- 工具函数用 camelCase: formatDate.ts
- 常量用 UPPER_SNAKE_CASE: MAX_RETRY_COUNT

## 错误处理
- 所有 API 调用必须用 try-catch 包裹
- 错误信息必须包含错误码和用户友好的提示
- 网络错误自动重试 3 次

# .cursor/rules/api-design.md

## REST API 规范
- 路由用 kebab-case: /user-profile
- 响应格式统一: { code: number, data: T, message: string }
- 分页参数: page (从1开始), pageSize (默认20)
- 认证: Bearer Token in Authorization header

## 数据库
- ORM: Prisma
- 软删除: deletedAt 字段
- 审计: createdBy, updatedBy 自动填充

规则文件支持 glob 模式匹配，可以针对不同类型的文件设置不同规则。

项目级规则（.cursorrules）示例：

# 项目概述
这是一个 Next.js 14 + TypeScript 的电商平台。

# 技术栈
- 前端：Next.js App Router + Tailwind + shadcn/ui
- 后端：Next.js Route Handlers + Prisma
- 数据库：PostgreSQL
- 认证：NextAuth.js
- 支付：Stripe

# 重要约定
- 所有价格用 integer（分为单位），显示时除以100
- 库存操作必须使用数据库事务
- 用户角色：admin, seller, buyer
- i18n: 使用 next-intl

多文件编辑的秘密

Cursor 最被低估的能力是跨文件编辑。当你用 Agent 模式时，它会自动追踪依赖链。

典型场景——添加一个新功能模块：

1. 你说"添加一个收藏功能"
2. Cursor 会：
   • 创建 models/Favorite.ts（数据模型）
   • 修改 prisma/schema.prisma（添加表定义）
   • 创建 app/api/favorites/route.ts（API 路由）
   • 创建 components/FavoriteButton.tsx（UI 组件）
   • 修改 lib/auth.ts（如果需要权限检查）
   • 生成 prisma/migrations/xxx.sql（数据库迁移）

这一切都是自动完成的。你只需要检查结果。

提高多文件编辑成功率的方法：

• 保持项目结构清晰和一致
• 善用 @file 引用关键文件
• 先用 Chat 模式讨论方案，再用 Agent 执行
• 每次修改后运行测试

@ 引用系统完全指南

@ 系统是 Cursor 的上下文注入机制。不同的 @ 类型提供不同维度的上下文：

实战技巧——组合引用：

@/app/api/users/route.ts @/models/User.ts 
这个 API 端点的输入验证不够严格。
参照 User model 的 Zod schema，
添加完整的请求体验证。

MCP 集成：扩展 Cursor 的能力边界

MCP（Model Context Protocol）让 Cursor 能连接外部工具和服务。

常用 MCP 服务器配置（.cursor/mcp.json）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

配置好后，Cursor Agent 可以直接查询数据库、操作 GitHub、访问文件系统。

实际用法示例：

用 postgres MCP 查询 users 表中最近7天注册的用户数量，
然后用 Chart.js 生成一个注册趋势图组件。

Cursor 会自动调用 MCP 服务器执行 SQL，拿到数据后生成前端组件。

提升效率的 10 个设置优化

在 Settings 中调整这些选项，体验会好很多：

1. 模型选择： 日常编码用 Claude Sonnet（快且便宜），复杂重构用 Claude Opus 或 GPT-4o。

2. Tab 补全模型： 用 cursor-small（免费且快速）。

3. 自动保存： 开启 "Auto Save" + "After Delay"，避免手动保存干扰工作流。

4. 上下文窗口： 调大 "Max Context Tokens" 到 128K，让 Agent 模式能看到更多代码。

5. 忽略文件： 在 .cursorignore 中排除 node_modules、dist、.env 等目录。

6. 长上下文聊天： 开启 "Long Context Chat"，处理大文件时不会截断。

7. 代码库索引： 确保开启了 "Codebase Indexing"，Agent 搜索才能高效。

8. Diff 审查模式： 开启 "Always Review Diffs"，养成审查 AI 修改的习惯。

9. 终端权限： 设置 "Run Commands Automatically"，但限制为安全命令（npm install、git status 等）。

10. 自定义片段： 创建常用代码片段模板，配合 Tab 补全使用。

常见坑与解决方案

坑 1：Cursor 生成的代码不一致

原因：上下文不够。解决方法：用 @ 引用相关文件，或者在 .cursorrules 中写明约定。

坑 2：Agent 模式陷入循环

原因：Prompt 太模糊。解决方法：拆分成明确的小步骤，给具体的文件引用。

坑 3：Token 消耗太快

原因：每次对话都发送大量上下文。解决方法：开启 "Codebase Indexing" 让 Cursor 自己搜索，而不是把所有文件都 @ 进去。

坑 4：Cursor 改错了不该改的文件

原因：Agent 模式的编辑范围太大。解决方法：开启 Diff 审查，每次修改都确认。

总结：Cursor 使用进阶路线图

第 1 周： 熟悉 Tab 补全 + Cmd+K，完成日常编码任务。

第 2 周： 学习 @ 引用系统，学会精确控制 Cursor 的上下文。

第 3 周： 开始使用 Agent 模式处理复杂任务，配置 .cursorrules。

第 4 周： 接入 MCP 服务器，让 Cursor 连接你的工具链。

持续优化： 根据项目特点持续完善规则文件和 MCP 配置。

记住：Cursor 的能力上限取决于你给它的上下文质量。花时间写好规则和 Prompt，回报是 10 倍的效率提升。

本文基于 Cursor 0.45+ 版本编写，部分功能可能在旧版本中不可用。建议始终保持最新版本以获取最佳体验。