Cursor 完全上手指南：AI 时代的代码编辑器

如果说 2023 年是 AI 编程的元年，那么 2024-2025 年就是 AI 编程工具爆发的时代。在众多工具中，Cursor 凭借其极致的用户体验和强大的 AI 能力，成为了开发者的新宠。今天，让我们从零开始，全面掌握这款”AI 时代的代码编辑器”。

第一章：认识 Cursor

什么是 Cursor？

Cursor 是一款基于 VS Code 深度定制的 AI 代码编辑器，由 Anysphere 公司开发。它不是简单的 AI 插件集成，而是将 AI 能力融入到编辑器的每一个角落，从底层重新设计了人机交互方式。

Cursor = VS Code 的熟悉体验 + 原生 AI 能力 + Agent 级别的代码理解

为什么选择 Cursor？

与 VS Code + Copilot 的对比

维度	Cursor	VS Code + Copilot
集成方式	原生集成，AI 是核心	插件形式，AI 是附加
上下文理解	整个 Codebase	主要是当前文件
Agent 能力	支持，可自主完成多步任务	不支持
跨文件编辑	原生支持	不支持
@ 引用系统	丰富，10+ 种引用类型	有限
终端命令执行	Agent 可自主执行	不支持
多模态输入	支持图片、文档	有限支持
价格	$20/月 (Pro)	$10/月

Cursor 的核心优势

1. 原生 AI 体验：AI 不是”附加功能”，而是编辑器的灵魂
2. 深度上下文感知：理解整个代码库的结构、依赖、风格
3. Agent 模式：能够自主规划并执行复杂的多步骤任务
4. 多模态交互：支持代码、图片、文档、网页等多种输入
5. 灵活的 @ 引用：精确控制 AI 获取的上下文信息
6. 项目级规则：通过 Rules 让 AI 理解并遵循团队规范

Cursor 的发展历程

• 2023 年初：Cursor 首次发布，主打 AI-first 编辑器概念
• 2023 年中：引入 Composer 功能，开启 Agent 模式探索
• 2024 年：全面升级 Agent 能力，支持 Claude 3.5 Sonnet
• 2025 年：MCP 协议支持、Background Agent、多模态增强
• 2026 年：Claude Opus 4 集成，Agent 能力再次飞跃

第二章：安装与配置

下载安装

Step 1：下载

1. 访问 Cursor 官网
2. 点击 “Download” 按钮
3. 选择对应系统版本：
   • macOS：支持 Intel 和 Apple Silicon
   • Windows：支持 Windows 10/11
   • Linux：提供 .deb 和 .AppImage 格式

Step 2：安装

macOS：

# 下载后解压，拖入 Applications 文件夹
# 或使用 Homebrew
brew install --cask cursor

Windows：

• 运行下载的 .exe 安装程序
• 按提示完成安装

Linux：

# Debian/Ubuntu
sudo dpkg -i cursor_*.deb

# 或使用 AppImage
chmod +x cursor_*.AppImage
./cursor_*.AppImage

Step 3：首次启动

1. 打开 Cursor
2. 选择登录方式（GitHub / Google / Email）
3. 完成账号注册或登录
4. 选择是否从 VS Code 导入设置（推荐导入）

从 VS Code 无痛迁移

Cursor 提供了完整的 VS Code 迁移方案，让你无需重新配置。

自动迁移

首次启动时，Cursor 会询问是否导入 VS Code 设置。选择导入后，以下内容会被迁移：

• ✅ 所有扩展（Extensions）
• ✅ 用户设置（settings.json）
• ✅ 键盘快捷键（keybindings.json）
• ✅ 代码片段（Snippets）
• ✅ 主题和图标

手动迁移

如果跳过了首次导入，可以手动触发：

1. 按 Cmd/Ctrl + Shift + P 打开命令面板
2. 搜索 Cursor: Import VS Code Settings
3. 选择要导入的内容

扩展兼容性

Cursor 基于 VS Code，99% 的 VS Code 扩展都能正常工作，包括：

• ESLint / Prettier
• GitLens
• Docker
• Remote SSH
• 各种语言扩展（Python、Go、Rust 等）

少数不兼容的扩展主要是其他 AI 编程插件（如 Copilot），因为可能与 Cursor 的 AI 功能冲突。

AI 模型配置

可用模型

进入 Settings > Models，可以选择以下模型：

模型	特点	推荐场景
Claude Opus 4	最强推理能力，代码质量最高	复杂架构设计、疑难 Bug
Claude 3.5 Sonnet	性价比之王，速度快质量高	日常开发首选
GPT-4o	通用能力强，多语言支持好	需要广泛知识的任务
GPT-4o mini	速度快，适合简单任务	Tab 补全、简单问答
cursor-small	Cursor 自研小模型	Tab 补全优化

模型选择策略

日常开发：Claude 3.5 Sonnet（平衡速度和质量）
复杂任务：Claude Opus 4（最强推理）
快速补全：GPT-4o mini 或 cursor-small
需要最新知识：GPT-4o（训练数据更新）

使用自定义 API

如果你有自己的 API Key，可以配置自定义模型：

1. 进入 Settings > Models
2. 点击 “Add Model”
3. 选择提供商（OpenAI / Anthropic / Azure 等）
4. 输入 API Key 和 Endpoint

这样可以：

• 使用自己的配额，不受 Cursor 限制
• 接入公司内部的私有模型
• 使用其他兼容 OpenAI API 的服务

关键设置项

打开设置（Cmd/Ctrl + ,），搜索以下关键配置：

AI 相关设置

{
  // Tab 补全
  "cursor.cpp.enablePartialAccepts": true,  // 允许部分接受
  "cursor.cpp.copilotStyle": "inline",      // 补全样式
  
  // Chat 设置
  "cursor.chat.showSuggestedFiles": true,   // 显示建议文件
  
  // Agent 设置  
  "cursor.composer.enabled": true,          // 启用 Composer
  
  // 隐私设置
  "cursor.privacy.mode": "normal"           // 或 "private"
}

隐私模式

如果你的代码有保密要求，可以开启隐私模式：

1. Settings > Privacy Mode
2. 开启后，你的代码不会被存储或用于训练

第三章：核心功能详解

1. Tab 智能补全

Tab 补全是 Cursor 最基础也是使用频率最高的功能。它远超传统的代码提示，能够预测你接下来要写的整段代码。

基本使用

• 触发：正常编码时自动触发，显示灰色预览
• 接受：按 Tab 接受全部补全
• 拒绝：按 Esc 拒绝补全
• 部分接受：按 Cmd/Ctrl + → 逐词接受

补全能力展示

场景 1：根据注释补全实现

# 计算两个日期之间的工作日数量，排除周末和节假日
def count_working_days(start_date, end_date, holidays=None):
    # 光标在这里，按 Tab...
    
    # Cursor 会补全：
    if holidays is None:
        holidays = []
    
    working_days = 0
    current = start_date
    
    while current <= end_date:
        if current.weekday() < 5 and current not in holidays:
            working_days += 1
        current += timedelta(days=1)
    
    return working_days

场景 2：根据函数签名补全

// 只需要写好类型签名
function parseQueryString(url: string): Record<string, string> {
    // Tab 补全完整实现
}

// Cursor 会补全：
function parseQueryString(url: string): Record<string, string> {
    const params: Record<string, string> = {};
    const queryString = url.split('?')[1];
    
    if (!queryString) return params;
    
    queryString.split('&').forEach(pair => {
        const [key, value] = pair.split('=');
        params[decodeURIComponent(key)] = decodeURIComponent(value || '');
    });
    
    return params;
}

场景 3：重复模式识别

// 写了第一个，Cursor 能预测后续的模式
const userSchema = {
    name: { type: String, required: true },
    // Tab 会补全类似的字段定义
    email: { type: String, required: true, unique: true },
    password: { type: String, required: true, minlength: 8 },
    createdAt: { type: Date, default: Date.now },
};

高级技巧

技巧 1：多候选切换

当有多个补全候选时：

• Alt + ] 查看下一个候选
• Alt + [ 查看上一个候选

技巧 2：部分接受的妙用

有时候补全的大部分正确，但有小错误。使用 Cmd/Ctrl + → 逐词接受，到错误处停止，手动修改后继续。

技巧 3：写好上下文

补全质量取决于上下文。提高补全质量的方法：

• 写清晰的函数/变量命名
• 添加类型注解（TypeScript、Python type hints）
• 写简短的注释说明意图

2. Chat 对话（Cmd/Ctrl + L）

Chat 是与 AI 进行对话的窗口，适合问答、讨论、代码解释等场景。

基本使用

打开方式：

• 快捷键 Cmd/Ctrl + L
• 点击右侧边栏的 Chat 图标

基本对话：

User: 解释一下 JavaScript 的事件循环机制

AI: JavaScript 的事件循环（Event Loop）是...

带上下文的对话

选中代码后对话：

1. 在编辑器中选中一段代码
2. 按 Cmd/Ctrl + L
3. 选中的代码会自动带入对话

User: [选中的代码自动显示]
      这段代码有什么问题？

AI: 我看了这段代码，发现以下问题：
    1. 第 5 行存在潜在的空指针异常...
    2. 第 12 行的循环可以优化...

使用 @ 引用添加上下文：

User: @src/utils/auth.ts @src/types/user.ts
      帮我分析这两个文件的关系，以及 auth.ts 中的类型定义是否正确

AI: 让我分析这两个文件...

Chat 的特色功能

1. Apply 按钮

当 AI 回复中包含代码时，会显示 “Apply” 按钮。点击后可以：

• 直接应用到当前文件
• 选择应用到指定文件
• 创建新文件

2. 历史管理

• 点击 Chat 面板顶部的标题可以查看历史对话
• 每个对话自动保存，可以随时回顾
• 支持搜索历史对话

3. 多轮对话

Chat 保持对话上下文，可以进行多轮讨论：

User: 帮我写一个 React 登录组件

AI: [生成基础组件]

User: 加上表单验证

AI: [在之前代码基础上添加验证]

User: 再加上 loading 状态和错误提示

AI: [继续完善]

Chat vs Composer 的选择

场景	推荐
问问题、讨论方案	Chat
解释代码	Chat
修改单个文件	Chat（然后 Apply）
跨文件修改	Composer
创建新功能	Composer
执行终端命令	Composer

3. Inline Edit（Cmd/Ctrl + K）

Inline Edit 让你在代码中直接进行 AI 编辑，无需切换窗口，是最快捷的编辑方式。

基本使用

1. 选中代码（或将光标放在要插入的位置）
2. 按 Cmd/Ctrl + K
3. 在弹出的输入框中输入指令
4. 查看预览（绿色=新增，红色=删除）
5. 按 Enter 接受，Esc 拒绝

详细使用场景

场景 1：修改现有代码

// 选中这个函数
function fetchUser(id) {
    return fetch(`/api/users/${id}`).then(r => r.json());
}

// Cmd+K，输入："添加错误处理、超时控制和重试机制"

// 结果：
async function fetchUser(id, retries = 3) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 5000);
    
    for (let i = 0; i < retries; i++) {
        try {
            const response = await fetch(`/api/users/${id}`, {
                signal: controller.signal
            });
            
            if (!response.ok) {
                throw new Error(`HTTP ${response.status}`);
            }
            
            return await response.json();
        } catch (error) {
            if (i === retries - 1) throw error;
            await new Promise(r => setTimeout(r, 1000 * (i + 1)));
        } finally {
            clearTimeout(timeout);
        }
    }
}

场景 2：在光标位置插入代码

class UserService:
    def __init__(self, db):
        self.db = db
    
    # 光标在这里，Cmd+K
    # 输入："添加一个根据 ID 批量查询用户的方法，支持分页"
    
    def get_users_by_ids(self, ids: List[int], page: int = 1, size: int = 20) -> List[User]:
        """批量查询用户，支持分页"""
        offset = (page - 1) * size
        return self.db.query(User).filter(
            User.id.in_(ids)
        ).offset(offset).limit(size).all()

场景 3：重构代码

// 选中一段冗长的条件判断
if (user && user.profile && user.profile.settings && user.profile.settings.theme) {
    theme = user.profile.settings.theme;
} else {
    theme = 'default';
}

// Cmd+K，输入："使用 optional chaining 重构"

// 结果：
const theme = user?.profile?.settings?.theme ?? 'default';

场景 4：添加文档注释

# 选中函数签名
def calculate_compound_interest(principal, rate, time, n=12):

# Cmd+K，输入："添加详细的 docstring，包含参数说明和示例"

# 结果：
def calculate_compound_interest(principal, rate, time, n=12):
    """
    计算复利终值
    
    Args:
        principal (float): 本金
        rate (float): 年利率（小数形式，如 0.05 表示 5%）
        time (int): 投资年限
        n (int): 每年复利次数，默认 12（月复利）
    
    Returns:
        float: 复利终值
    
    Example:
        >>> calculate_compound_interest(10000, 0.05, 3)
        11614.72
        >>> calculate_compound_interest(10000, 0.05, 3, n=1)
        11576.25
    """

Inline Edit 的优势

• 快：不用切换窗口，在代码中直接操作
• 精准：明确指定要修改的代码范围
• 可预览：修改前可以看到 diff 预览
• 可撤销：不满意可以 Esc 取消，或 Cmd+Z 撤销

4. Composer / Agent 模式（Cmd/Ctrl + I）

Composer 是 Cursor 最强大的功能，也是区别于其他 AI 编程工具的核心能力。它是一个真正的 AI Agent，能够自主规划、跨文件操作、执行命令。

什么是 Agent 模式？

传统的 AI 编程助手是”问答式”的——你问一个问题，它给一个答案。

Agent 模式是”任务式”的——你描述一个目标，AI 自主规划步骤、执行操作、处理错误，直到完成任务。

传统模式：
User: 怎么创建一个 Express 服务器？
AI: 你需要这样做... [给出代码]
User: [手动复制粘贴]
User: 怎么添加路由？
AI: 你需要这样... [给出代码]
User: [手动复制粘贴]
...

Agent 模式：
User: 帮我创建一个 Express 后端，包含用户 CRUD API，使用 MongoDB
AI: [自动执行]
    1. 创建项目结构
    2. 安装依赖 (npm install)
    3. 创建 server.js
    4. 创建 routes/users.js
    5. 创建 models/User.js
    6. 创建 config/db.js
    7. 更新 package.json scripts
    完成！

基本使用

打开方式：

• 快捷键 Cmd/Ctrl + I
• 点击顶部的 “Composer” 按钮

输入任务描述后，Agent 会：

1. 分析任务，制定计划
2. 读取相关文件理解上下文
3. 逐步执行修改
4. 需要时创建新文件
5. 需要时执行终端命令
6. 遇到问题会尝试修复

Agent 能做什么？

1. 跨文件修改

@src/components/ @src/hooks/ @src/types/

把所有组件从 class 组件重构为函数式组件 + Hooks，
并将公共逻辑提取到 hooks 目录

Agent 会：

• 遍历所有组件文件
• 逐个重构为函数式组件
• 识别重复逻辑，创建自定义 Hooks
• 更新相关的类型定义
• 确保所有导入正确

2. 创建完整功能

创建一个用户评论功能：
- 前端：评论列表组件、评论表单组件、评论 item 组件
- 后端：评论 API（CRUD）
- 数据库：评论模型
- 支持嵌套回复、点赞、举报

Agent 会创建 10+ 个文件，包含完整的前后端代码。

3. 执行终端命令

初始化一个 Next.js 项目，使用 TypeScript、Tailwind、Prisma，
并配置好 ESLint 和 Prettier

Agent 会执行：

npx create-next-app@latest my-app --typescript --tailwind
cd my-app
npm install prisma @prisma/client
npx prisma init
npm install -D eslint prettier eslint-config-prettier
# ... 然后创建配置文件

4. Debug 和修复

@terminal 
运行 npm run build 报错了，帮我分析并修复所有错误

Agent 会：

• 分析错误信息
• 定位问题文件
• 逐个修复问题
• 重新运行验证

Agent 模式的工作流程

输入任务
    ↓
制定计划（显示将要进行的操作）
    ↓
用户确认（可以在这里调整）
    ↓
逐步执行
    ├── 读取文件
    ├── 修改文件（显示 diff）
    ├── 创建文件
    ├── 执行命令
    └── 处理错误
    ↓
完成（或遇到需要用户决策的情况）

Agent 使用最佳实践

1. 任务描述要清晰

❌ 不好：帮我优化代码
✅ 好：@src/utils/data-processing.ts 
      优化这个文件的性能：
      1. 减少不必要的数组遍历
      2. 使用 Map 替代多次 find
      3. 添加缓存机制

2. 给足上下文

❌ 不好：添加一个登录功能
✅ 好：@src/pages/ @src/api/ @src/types/
      参考现有页面风格，添加登录功能：
      - 使用现有的 API 调用模式
      - 复用现有的表单组件
      - 登录成功后跳转到 /dashboard

3. 分阶段执行复杂任务

对于特别复杂的任务，建议分阶段：

阶段 1：先创建数据模型和类型定义
阶段 2：实现后端 API
阶段 3：实现前端页面
阶段 4：添加测试

4. 审查 Agent 的操作

Agent 执行每一步时都会显示预览。养成习惯：

• 检查文件修改是否合理
• 检查新创建的文件内容
• 检查要执行的命令是否安全

5. @ 引用系统（重点）

@ 引用是 Cursor 最重要的特性之一。它让你精确控制 AI 获取的上下文，是提高 AI 输出质量的关键。

完整的引用类型

引用	说明	使用场景
@文件	引用特定文件	讨论特定文件的代码
@文件夹/	引用整个目录	理解模块结构
@Codebase	语义搜索代码库	查找相关代码
@Web	搜索互联网	获取最新信息
@Docs	引用技术文档	参考官方文档
@Git	引用 Git 信息	查看变更历史
@Definitions	引用符号定义	跳转到定义
@Problems	引用当前错误	Debug 问题
@Terminal	引用终端输出	分析命令结果
@Clipboard	引用剪贴板	粘贴外部内容
@Notepads	引用笔记	参考记录的信息

详细使用说明

@文件 —— 引用特定文件

@src/components/Button.tsx 这个组件的 props 设计合理吗？

可以同时引用多个文件：

@src/api/users.ts @src/types/user.ts @src/hooks/useUser.ts
这三个文件的类型定义是否一致？

@文件夹/ —— 引用整个目录

注意末尾的 /，表示引用目录：

@src/components/ 分析这个目录的组件结构，有没有可以合并的重复组件？

@Codebase —— 语义搜索

当你不知道代码在哪里时，使用 @Codebase 进行语义搜索：

@Codebase 用户认证相关的代码在哪里？

@Codebase 哪里处理了支付回调？

@Codebase 找到所有使用 localStorage 的地方

与直接搜索不同，@Codebase 是语义理解的，能找到”相关”的代码而不仅是文本匹配。

@Web —— 搜索互联网

获取最新信息或 AI 训练数据中没有的内容：

@Web React 19 的新特性有哪些？

@Web Tailwind CSS 4.0 的安装方法

@Web 2026 年最新的 TypeScript 配置最佳实践

@Docs —— 引用技术文档

Cursor 内置了主流框架/库的文档索引：

@Docs React      → 引用 React 官方文档
@Docs NextJS     → 引用 Next.js 文档
@Docs Prisma     → 引用 Prisma 文档
@Docs TailwindCSS → 引用 Tailwind 文档

使用方法：

@Docs React 如何正确使用 useEffect 的依赖数组？

@Docs NextJS App Router 的 loading.tsx 怎么用？

@Git —— 引用 Git 信息

@Git diff         → 查看当前未提交的修改
@Git log          → 查看提交历史
@Git blame        → 查看文件的修改记录
@Git branch       → 查看分支信息

使用场景：

@Git diff 帮我审查这些修改，有没有问题？

@Git log 最近一周的提交都改了什么？

@Git 为什么这个文件最近改动这么多？

@Definitions —— 引用符号定义

当你想了解某个类型、函数、类的定义时：

@Definitions UserProfile 这个类型的完整定义是什么？

@Problems —— 引用当前错误

引用编辑器中显示的 lint 错误和警告：

@Problems 帮我修复当前文件的所有错误

@Terminal —— 引用终端输出

当命令执行出错时，引用终端输出让 AI 分析：

@Terminal 这个报错是什么原因？怎么解决？

@ 引用的组合使用

@ 引用的真正威力在于组合使用：

@src/pages/Login.tsx 
@src/api/auth.ts 
@src/hooks/useAuth.ts
@Docs NextAuth

参考这些文件的现有实现和 NextAuth 文档，
帮我添加 Google OAuth 登录功能

@Codebase 支付相关
@Docs Stripe
@Web Stripe Webhook 最佳实践 2026

重构我们的支付模块，按照最新最佳实践实现

第四章：Cursor Rules 详解

Cursor Rules 让你可以为项目定义 AI 的行为规则，确保生成的代码符合团队规范，是提高 AI 输出一致性的关键。

Rules 的类型

1. 项目级 Rules

在项目根目录创建 .cursor/rules 文件（或 .cursorrules 文件）：

my-project/
├── .cursor/
│   └── rules          ← 项目 Rules
├── src/
└── package.json

2. 目录级 Rules

可以在子目录创建 Rules，会覆盖上级 Rules：

my-project/
├── .cursor/rules              ← 项目通用规则
├── src/
│   ├── frontend/
│   │   └── .cursor/rules      ← 前端特定规则
│   └── backend/
│       └── .cursor/rules      ← 后端特定规则

3. 全局 Rules

在 Settings > Rules 中设置，适用于所有项目。

Rules 的写法

基础结构

# 项目名称：电商平台

## 技术栈
- 前端：React 18 + TypeScript + Zustand + TanStack Query
- 后端：Node.js + Express + Prisma + PostgreSQL
- 样式：Tailwind CSS
- 测试：Vitest + Testing Library

## 代码规范

### TypeScript
- 使用 strict 模式
- 禁止使用 any，必须显式定义类型
- 接口使用 interface，类型别名使用 type
- 所有函数必须有返回类型注解

### React
- 只使用函数式组件 + Hooks
- 组件文件使用 PascalCase：`UserProfile.tsx`
- Hooks 文件使用 camelCase：`useUserProfile.ts`
- Props 类型定义在组件文件内，使用 interface

### 命名规范
- 变量/函数：camelCase
- 类/组件/接口：PascalCase
- 常量：UPPER_SNAKE_CASE
- 私有属性：_camelCase

## 目录结构

src/
├── components/ # 通用组件
│ ├── ui/ # 基础 UI 组件
│ └── business/ # 业务组件
├── features/ # 功能模块
│ └── [feature]/
│ ├── components/
│ ├── hooks/
│ ├── api/
│ └── types/
├── hooks/ # 全局 Hooks
├── api/ # API 客户端
├── types/ # 全局类型
└── utils/ # 工具函数

## API 设计规范
- 使用 RESTful 风格
- 响应格式：{ success: boolean, data?: T, error?: string }
- 错误码：4xx 客户端错误，5xx 服务端错误

## 错误处理
- 前端：使用 Error Boundary 捕获组件错误
- 后端：使用中间件统一处理错误
- 所有异步操作必须有 try-catch

## 注释规范
- 使用中文注释
- 复杂逻辑必须有注释说明
- 函数必须有 JSDoc 注释

高级 Rules 技巧

1. 指定代码示例

## 组件模板

新建 React 组件时，请使用以下模板：

```tsx
interface ${ComponentName}Props {
  // props 定义
}

export const ${ComponentName}: React.FC<${ComponentName}Props> = (props) => {
  const { } = props;
  
  return (
    <div className="">
      
    </div>
  );
};

**2. 指定禁止的模式**

```markdown
## 禁止的做法

- ❌ 不要使用 `var`
- ❌ 不要使用 `any` 类型
- ❌ 不要在组件中直接调用 API，使用 hooks
- ❌ 不要使用 inline style，使用 Tailwind
- ❌ 不要 commit console.log

3. 指定偏好的库

## 技术选型偏好

| 场景 | 使用 | 不使用 |
|------|------|--------|
| 状态管理 | Zustand | Redux, MobX |
| 数据请求 | TanStack Query | SWR, 手动 fetch |
| 表单 | React Hook Form | Formik |
| 日期 | dayjs | moment |
| HTTP | axios | fetch |

4. 指定 AI 行为

## AI 助手行为

1. 生成代码后，简要解释实现思路
2. 如果有多种实现方案，列出各自优缺点
3. 修改代码时，说明修改了哪些地方以及原因
4. 发现潜在 bug 时主动指出
5. 遵循现有代码风格，不要引入新的模式

Rules 的生效范围

Rules 的加载顺序（后面的覆盖前面的）：

1. Cursor 内置默认规则
2. 用户全局 Rules（Settings）
3. 项目根目录 Rules
4. 子目录 Rules
5. 对话中的显式指令

第五章：高级功能

1. 多模态输入：图片

Cursor 支持在对话中使用图片，非常适合 UI 相关的开发。

使用方式

1. 在 Chat 或 Composer 中，点击”添加附件”按钮
2. 选择图片文件（支持 PNG、JPG、GIF、WebP）
3. 或者直接从剪贴板粘贴截图

使用场景

场景 1：根据设计稿生成代码

[粘贴 UI 设计图]

根据这个设计图，使用 React + Tailwind CSS 实现这个卡片组件

场景 2：Debug UI 问题

[粘贴 Bug 截图]

@src/components/Card.tsx
这个组件渲染出来和预期不一样，图片是实际效果，帮我找出问题

场景 3：描述复杂交互

[粘贴交互流程图]

实现图中描述的拖拽排序功能

2. Notepads：持久化的上下文

Notepads 是 Cursor 的笔记功能，可以保存常用的上下文信息，在对话中用 @Notepads 引用。

创建 Notepad

1. 点击左侧边栏的 Notepads 图标
2. 点击 “New Notepad”
3. 输入内容并保存

使用场景

场景 1：保存架构设计

创建一个 “架构设计” Notepad：

# 系统架构

## 服务划分
- user-service: 用户管理
- order-service: 订单处理
- payment-service: 支付处理
- notification-service: 消息通知

## 通信方式
- 同步：REST API
- 异步：RabbitMQ

## 数据库
- PostgreSQL: 用户、订单
- MongoDB: 日志、消息
- Redis: 缓存、会话

使用时：

@Notepads 架构设计

在 user-service 中添加用户等级功能

场景 2：保存 API 规范

# API 规范

## 请求格式
Content-Type: application/json
Authorization: Bearer {token}

## 响应格式
{
  "code": 200,
  "message": "success",
  "data": { ... }
}

## 错误码
- 400: 参数错误
- 401: 未授权
- 403: 禁止访问
- 404: 资源不存在
- 500: 服务器错误

3. MCP（Model Context Protocol）

MCP 是 Cursor 支持的扩展协议，可以让 AI 连接外部工具和服务。

什么是 MCP？

MCP 允许 Cursor 的 AI 访问：

• 浏览器（查看网页、交互）
• 数据库（查询数据）
• API 服务（调用外部服务）
• 本地工具（文件处理等）

内置 MCP：Browser

Cursor 内置了浏览器 MCP，可以用于前端开发和测试。

用 MCP 浏览器打开 http://localhost:3000
检查页面是否正常渲染

AI 可以：

• 打开网页
• 截取屏幕
• 点击、输入等交互
• 分析页面内容

配置外部 MCP

在项目中创建 .cursor/mcp.json：

{
  "servers": {
    "database": {
      "command": "npx",
      "args": ["mcp-server-postgres", "postgresql://..."]
    }
  }
}

配置后，AI 可以直接查询数据库来理解数据结构。

4. Background Agent（后台 Agent）

Background Agent 允许 Agent 在后台持续运行，适合长时间的任务。

使用场景

• 大规模代码重构
• 运行和监控测试
• 持续集成任务
• 长时间的生成任务

使用方式

在 Composer 中输入任务后，选择 “Run in Background”。

Agent 会在后台执行，你可以继续其他工作。完成后会通知你。

第六章：实战工作流

工作流 1：从零开始一个新项目

Step 1: 初始化项目
─────────────────
Cmd+I (Composer)

"创建一个 Next.js 14 项目：
- TypeScript
- Tailwind CSS
- Prisma + PostgreSQL
- NextAuth 认证
- 配置好 ESLint、Prettier
- 创建基础目录结构"

[Agent 自动执行命令，创建文件]

Step 2: 定义规范
─────────────────
创建 .cursor/rules 文件，写入项目规范

Step 3: 创建数据模型
─────────────────
"@prisma/schema.prisma
创建用户、文章、评论的数据模型，
包含关联关系"

Step 4: 开发功能
─────────────────
"@src/
创建文章列表页面，包含：
- 分页
- 搜索
- 分类筛选"

Step 5: 迭代完善
─────────────────
根据需要继续添加功能...

工作流 2：重构遗留代码

Step 1: 理解现状
─────────────────
Cmd+L (Chat)

"@src/legacy/
分析这个目录的代码：
1. 整体架构
2. 主要问题
3. 依赖关系"

Step 2: 制定计划
─────────────────
"基于你的分析，给出重构计划，
分阶段进行，每阶段保持可运行"

Step 3: 逐步重构
─────────────────
Cmd+I (Composer)

"执行重构计划的第一阶段：
[具体内容]
确保测试通过"

Step 4: 验证
─────────────────
"运行测试，确认功能正常"

Step 5: 继续下一阶段
─────────────────
...

工作流 3：Debug 流程

Step 1: 复现问题
─────────────────
确认问题存在，收集错误信息

Step 2: 分析错误
─────────────────
Cmd+L

"@Terminal 
@src/api/users.ts

运行时报错 [错误信息]
帮我分析原因"

Step 3: 定位代码
─────────────────
"@Codebase 
这个错误涉及到哪些文件？"

Step 4: 修复
─────────────────
Cmd+K (在问题代码上)

"修复这个 null pointer 问题，
添加必要的判空处理"

Step 5: 验证
─────────────────
重新运行，确认问题解决

工作流 4：添加新功能

Step 1: 理解需求
─────────────────
明确功能需求

Step 2: 了解现有代码
─────────────────
Cmd+L

"@Codebase 用户模块
@src/types/

现有的用户模块是怎么实现的？
我要添加用户积分功能，应该怎么集成？"

Step 3: 设计方案
─────────────────
"给出用户积分功能的设计方案：
- 数据模型
- API 设计
- 前端页面
考虑与现有代码的兼容"

Step 4: 实现
─────────────────
Cmd+I (分步骤实现)

"先实现积分的数据模型和 API"

"接着实现积分的前端展示"

"最后添加积分变动的日志记录"

Step 5: 测试
─────────────────
"为积分功能添加单元测试"

第七章：快捷键完全指南

核心快捷键

功能	Mac	Windows/Linux	说明
Chat	Cmd + L	Ctrl + L	打开/聚焦 Chat 面板
Inline Edit	Cmd + K	Ctrl + K	在代码中直接编辑
Composer	Cmd + I	Ctrl + I	打开 Agent 模式
命令面板	Cmd + Shift + P	Ctrl + Shift + P	打开命令面板

Tab 补全相关

功能	Mac	Windows/Linux
接受补全	Tab	Tab
拒绝补全	Esc	Esc
部分接受（逐词）	Cmd + →	Ctrl + →
下一个候选	Alt + ]	Alt + ]
上一个候选	Alt + [	Alt + [

Chat 相关

功能	Mac	Windows/Linux
新对话	Cmd + N (在 Chat 中)	Ctrl + N
清除对话	Cmd + Shift + L	Ctrl + Shift + L
选中代码后添加到 Chat	Cmd + L	Ctrl + L

Inline Edit 相关

功能	Mac	Windows/Linux
接受修改	Enter	Enter
拒绝修改	Esc	Esc
查看 diff	自动显示	自动显示

编辑器通用

功能	Mac	Windows/Linux
设置	Cmd + ,	Ctrl + ,
撤销	Cmd + Z	Ctrl + Z
重做	Cmd + Shift + Z	Ctrl + Y
查找	Cmd + F	Ctrl + F
全局搜索	Cmd + Shift + F	Ctrl + Shift + F
跳转到文件	Cmd + P	Ctrl + P
跳转到符号	Cmd + Shift + O	Ctrl + Shift + O

第八章：常见问题与解决

Q1: Cursor 响应很慢怎么办？

可能原因：

1. 模型服务器繁忙
2. 项目太大，索引慢
3. 网络问题

解决方案：

• 尝试切换模型（如从 Opus 4 切换到 Sonnet）
• 在 .cursorignore 中排除大文件夹（node_modules, dist）
• 检查网络连接

Q2: AI 生成的代码不符合项目风格？

解决方案：

1. 创建详细的 .cursor/rules 文件
2. 使用 @ 引用现有代码作为示例
3. 在 prompt 中明确指出要遵循的风格

@src/components/Button.tsx
参考这个组件的风格，创建一个 Modal 组件

Q3: Agent 执行命令后出错了？

解决方案：

1. 不要慌，Agent 通常会尝试自己修复
2. 如果 Agent 卡住，可以 Ctrl+C 中断
3. 分析错误信息，给 Agent 更多上下文
4. 考虑把任务拆分成更小的步骤

Q4: 如何让 AI 理解我的整个代码库？

方法：

1. 使用 @Codebase 进行语义搜索
2. 创建一个架构说明的 Notepad
3. 在 Rules 中描述项目结构
4. 引用关键文件让 AI 学习模式

Q5: Pro 版本值得购买吗？

值得的场景：

• 每天大量使用 AI 编程
• 需要使用 Claude Opus 4 等高级模型
• 团队协作需要统一工具

可以先用免费版的场景：

• 偶尔使用
• 主要用于学习
• 预算有限

Q6: 代码安全吗？会被用于训练吗？

Cursor 的隐私政策：

• 免费用户：代码可能被用于改进服务（但不是训练）
• Pro/Business 用户：代码不会被存储或用于任何目的
• 可以开启 Privacy Mode 完全禁止代码传输到服务器（此时只能使用本地模型）

Q7: 插件不兼容怎么办？

大部分 VS Code 插件都兼容，但可能冲突的：

• GitHub Copilot（功能重复）
• 其他 AI 编程插件
• 某些深度修改编辑器的插件

解决方案：

• 禁用冲突的插件
• 如果必须使用，在 Settings 中配置避免冲突

Q8: 如何有效提问让 AI 给出更好的答案？

提问公式：

上下文 + 目标 + 约束 + 格式要求

示例：
@src/api/
我需要添加一个订单取消的 API（目标）
要包含取消原因和退款处理（约束）
请按照现有 API 的风格实现，并添加注释（格式要求）

第九章：进阶之路

从新手到高手的学习路径

Level 1：基础使用
────────────────
□ 熟练使用 Tab 补全
□ 会用 Cmd+L 进行基本对话
□ 了解 @ 引用的基本用法

Level 2：高效使用
────────────────
□ 熟练使用 Cmd+K 进行 Inline Edit
□ 掌握常用 @ 引用类型
□ 建立项目 Rules

Level 3：Agent 使用
────────────────
□ 使用 Composer 完成多文件任务
□ 让 Agent 执行终端命令
□ 学会分解复杂任务

Level 4：专家级
────────────────
□ 精心设计 Rules 和 Notepads
□ 高效组合多种功能
□ 掌握 Debug 和重构工作流
□ 使用 MCP 扩展能力

持续学习资源

1. Cursor 官方文档：https://docs.cursor.sh
2. Cursor 社区：https://cursor.sh/community
3. YouTube 教程：搜索 “Cursor AI Tutorial”
4. Twitter/X：关注 @cursor_ai

总结

Cursor 代表了 AI 编程工具的未来方向——AI 不再是辅助，而是真正的编程伙伴。

掌握 Cursor 的核心要点：

1. 从简单功能开始：Tab 补全 → Chat → Inline Edit → Composer
2. 用好 @ 引用：给 AI 足够且精准的上下文
3. 配置好 Rules：让 AI 理解并遵循项目规范
4. 善用 Agent：让 AI 处理繁琐的多步骤任务
5. 持续迭代：根据使用体验不断优化 Rules 和工作流

最后的忠告：

工具只是工具。Cursor 能让你更快地实现想法，但编程思维、系统设计、问题解决能力才是核心竞争力。AI 能加速你的编码，但不能替代你的思考。

在 AI 时代，学会与 AI 协作比单纯学习编码更重要。Cursor 是这个新时代的绝佳入口。

Happy Coding with AI!