一、Cursor 核心定位：AI 原生编程助手

Cursor 是一款基于 VSCode 深度改造的 AI 原生代码编辑器，它不只是简单的代码补全工具，而是能全程参与你的开发流程：从需求理解、代码编写、Bug 调试到重构优化，像一位 24 小时在线的资深结对程序员。

它的核心价值在于：

降低认知负担：让 AI 处理重复、繁琐的编码工作，你专注于业务逻辑和架构设计
加速知识传递：新人可快速理解项目，老代码也能被 AI 高效解读
提升代码质量：实时提供重构建议、规范检查，减少潜在 Bug

二、高效能力：日常开发的四大核心武器

1. Chat 对话：随时待命的技术顾问

在编辑器右侧打开 Chat 面板，你可以随时向 AI 提问，无需切换工具打断开发流。

常见场景：

解释代码：选中一段复杂逻辑，提问「这段代码的作用是什么？有什么潜在问题？」
生成代码：输入需求「帮我写一个 React 函数组件，实现用户登录表单，包含表单验证」
查错：粘贴报错信息，让 AI 定位根因并给出修复方案
学习新技术：「帮我解释下 React 18 的 useTransition 钩子用法」

案例：你遇到一段看不懂的老代码：

const formatDate = (timestamp: number) => {
  const date = new Date(timestamp * 1000);
  return `${date.getFullYear()}-${(date.getMonth() + 1).toString().padStart(2, '0')}-${date.getDate().toString().padStart(2, '0')}`;
};

直接选中后在 Chat 中提问：「解释这段代码，并优化它的可读性」，AI 会输出：

这段代码将 Unix 时间戳（秒）转换为 YYYY-MM-DD 格式的日期字符串。优化建议：使用 Intl.DateTimeFormat 提升可读性和兼容性：
const formatDate = (timestamp: number): string => {
  const date = new Date(timestamp * 1000);
  return new Intl.DateTimeFormat('zh-CN', {
    year: 'numeric',
    month: '2-digit',
    day: '2-digit'
  }).format(date).replace(/\//g, '-');
};

2. Prompt 指令：精准控制 AI 输出

通过结构化的 Prompt，你可以让 AI 严格按照你的要求输出代码、文档或注释。

高效 Prompt 模板：

我需要你完成以下任务：
1. 功能需求：[清晰描述要实现的功能]
2. 技术栈：[指定使用的框架/库/语言版本]
3. 约束条件：[代码规范、性能要求、兼容性等]
4. 输出格式：[要求 AI 以何种格式输出，如代码片段、完整文件、步骤说明等]

案例：

我需要你完成以下任务：
1. 功能需求：写一个 Vue 3 组合式函数，实现防抖功能，支持立即执行选项
2. 技术栈：Vue 3 + TypeScript
3. 约束条件：代码要符合 TypeScript 类型规范，添加详细 JSDoc 注释
4. 输出格式：完整的函数代码 + 使用示例

AI 会直接输出可复用的代码：

import { ref, watch } from 'vue';

/**
 * 防抖函数组合式 API
 * @param fn 要执行的函数
 * @param delay 延迟时间（毫秒）
 * @param immediate 是否立即执行
 * @returns 防抖后的函数和取消方法
 */
export function useDebounce<T extends (...args: any[]) => any>(
  fn: T,
  delay: number,
  immediate: boolean = false
) {
  const timer = ref<NodeJS.Timeout | null>(null);

  const debouncedFn = (...args: Parameters<T>) => {
    if (timer.value) clearTimeout(timer.value);
    
    if (immediate && !timer.value) {
      fn(...args);
      immediate = false;
    } else {
      timer.value = setTimeout(() => {
        fn(...args);
        immediate = true;
      }, delay);
    }
  };

  const cancel = () => {
    if (timer.value) clearTimeout(timer.value);
    timer.value = null;
  };

  return { debouncedFn, cancel };
}

// 使用示例
const { debouncedFn } = useDebounce((val: string) => console.log(val), 500);
debouncedFn('test');

3. 函数解释：快速读懂代码的利器

选中任意函数或代码块，右键选择「Explain Code」或直接在 Chat 中提问，AI 会用通俗易懂的语言解释代码逻辑、依赖和潜在风险。

案例：选中 Node.js 中读取文件的代码：

const fs = require('fs').promises;
const path = require('path');

async function readConfigFile() {
  const configPath = path.join(__dirname, 'config.json');
  const data = await fs.readFile(configPath, 'utf8');
  return JSON.parse(data);
}

AI 解释：

这段代码定义了一个异步函数 readConfigFile，用于读取并解析项目根目录下的 config.json 文件：

引入 fs.promises 和 path 模块，使用 Promise 版文件 API 避免回调地狱

拼接配置文件的绝对路径

以 UTF-8 编码读取文件内容

将 JSON 字符串解析为对象并返回潜在风险：未处理文件不存在或 JSON 解析失败的异常，建议添加 try/catch。

4. 重构建议：让代码更优雅、可维护

AI 能识别代码中的「坏味道」，如冗余代码、重复逻辑、性能问题等，并给出可直接落地的重构方案。

案例：你有一段重复的表单验证代码：

const validateUsername = (username: string) => {
  if (!username) return '用户名不能为空';
  if (username.length < 3) return '用户名长度不能少于3位';
  return null;
};

const validatePassword = (password: string) => {
  if (!password) return '密码不能为空';
  if (password.length < 6) return '密码长度不能少于6位';
  return null;
};

AI 会建议重构为可复用的验证函数：

type Validator = (value: string) => string | null;

const createValidator = (
  requiredMsg: string,
  minLength: number,
  minLengthMsg: string
): Validator => {
  return (value: string) => {
    if (!value) return requiredMsg;
    if (value.length < minLength) return minLengthMsg;
    return null;
  };
};

const validateUsername = createValidator('用户名不能为空', 3, '用户名长度不能少于3位');
const validatePassword = createValidator('密码不能为空', 6, '密码长度不能少于6位');

三、结对编程：团队协作的高效场景

Cursor 非常适合作为结对编程工具，在以下场景中能发挥巨大价值：

1. 核心模块开发

你负责设计架构和接口，AI 帮你实现具体逻辑和边界处理
实时校验代码是否符合设计规范，提前发现潜在问题

2. 新人培训

新人打开项目后，通过 @Files & Folders 引入核心目录，让 AI 讲解项目结构
遇到不懂的代码，直接让 AI 解释，快速上手业务逻辑

3. 复杂问题 Debug

结合终端日志、代码上下文，让 AI 定位复杂 Bug 的根因
针对疑难问题，AI 能提供多种解决方案并分析优劣

四、三大工作模式：适配不同开发需求

1. Ask 模式

标准问答模式，适合单次需求：如解释代码、生成片段、查错等。

特点：轻量、快速，不保存上下文，适合临时问题。

2. Agent 模式

自动化智能体模式，适合复杂任务：如项目重构、批量修改文件、自动化部署等。

特点：AI 会自主分析需求、拆解任务、执行多步操作，无需你逐一下指令。
场景：「帮我把项目中所有的 console.log 替换为 logger 工具」「帮我自动化部署项目到服务器」

3. Manual 模式

手动控制上下文，适合精准需求：你通过 @ 命令主动添加文件、目录、日志等上下文，让 AI 回答更准确、不瞎编。

特点：可控性最强，适合需要严格依赖项目上下文的场景。
核心：@ 命令是 Manual 模式的灵魂，下文会详细讲解。

五、内联聊天：不打断编码流的高效交互

快捷键

Cmd + K（Mac）/ Ctrl + K（Windows）：内联唤起 AI 面板，直接在代码旁生成/修改代码
Cmd + L（Mac）/ Ctrl + L（Windows）：围绕当前选中行/代码块进行优化、解释、重构

优势：不用切出编辑页面，保持专注，所见即所得。

案例：你正在写一段循环逻辑，想优化为更简洁的数组方法：

const numbers = [1, 2, 3, 4, 5];
let doubled = [];
for (let i = 0; i < numbers.length; i++) {
  doubled.push(numbers[i] * 2);
}

选中这段代码，按 Cmd + L，输入「优化为数组方法」，AI 会直接在编辑器内替换为：

const numbers = [1, 2, 3, 4, 5];
const doubled = numbers.map(num => num * 2);

六、终端聊天：命令行一键生成

唤起：Cmd + K（Mac）/ Ctrl + K（Windows）
场景：快速生成 Shell 命令，无需记忆复杂语法

案例：你想查看所有 Node.js 进程，直接在终端输入 Cmd + K，提问「查看所有 Node.js 进程」，AI 会生成：

ps aux | grep node

并解释：

ps aux 列出所有进程，grep node 过滤出包含 node 的进程，你可以看到进程 ID、占用资源等信息。

七、Tab 智能补全：Cursor 王牌能力

Tab 补全支持文本与代码，是提升手速的核心功能，让你「只写思路，不写细节」。

1. 文本补全

自动续写注释、文案、文档，适合写 README、注释等场景。

2. 代码补全

通过注释驱动：写一行注释描述需求，AI 会自动生成对应代码
依赖良好命名规范：望文知意的变量/函数名、驼峰命名，能让 AI 更准确理解你的意图
配合 TS 类型：TypeScript 类型定义能让 AI 补全更精准，避免类型错误

案例：你写了一行注释：

// 过滤数组中大于10的偶数，并求和
const numbers = [1, 5, 12, 8, 20, 3];

按 Tab，AI 会自动补全：

const numbers = [1, 5, 12, 8, 20, 3];
const result = numbers.filter(num => num > 10 && num % 2 === 0).reduce((acc, curr) => acc + curr, 0);

3. 部分补全（精细控制）

不一次性接受整段代码，逐词接受，避免多余代码：

Cmd + →（Mac）/ Ctrl + →（Windows）：每次接受一个单词/一段

案例： AI 补全了一段完整代码，你只想接受前半部分：

const getUserInfo = async (userId: string) => {
  const res = await fetch(`/api/users/${userId}`);
  const data = await res.json();
  return { id: data.id, name: data.name, email: data.email };
};

按 Cmd + → 三次，先接受 const getUserInfo = async (userId: string) => {，再接受 const res = await fetch(/api/users/${userId});，最后接受剩余部分。

八、@ 命令：上下文精准控制（最重要）

@ 是 Cursor 最强大的功能之一，它决定了 AI「知道什么」，让你能精准控制上下文，避免 AI 瞎编。

核心 @ 命令详解

选项	功能说明	实战案例
Files & Folders	引入单个或多个文件/文件夹作为上下文，AI 会读取其内容来辅助你	`@Files & Folders` 选中 `src/components/` 目录，提问「帮我重构这个目录下的所有组件，统一使用 TypeScript 类型」
Code	快速选中代码作为上下文，针对某段逻辑优化、解释、修复	选中一段报错代码，`@Code` + 提问「修复这段代码的 Bug，并解释原因」
Docs	引入项目文档或官方文档，让 AI 基于文档知识回答问题	`@Docs` 添加 Vue 3 官网文档链接，提问「帮我用 Vue 3 最新 API 写一个计数器组件」
Terminals	引入终端输出日志，方便 AI 分析报错、命令执行结果	`@Terminals` 粘贴报错日志，提问「帮我定位这个编译错误的原因」
Past Chats	引入之前的对话记录，让 AI 延续上下文，避免重复说明	之前讨论过用户登录功能，`@Past Chats` 后提问「帮我在之前的基础上添加记住密码功能」
Branch (Diff with Main)	引入当前分支与 main 分支的代码差异，AI 可以基于变更内容做代码评审、解释改动、生成 PR 描述	`@Branch (Diff with Main)`，提问「帮我生成这段代码的 PR 描述，并检查是否有潜在问题」
Linter Errors	自动修复 ESLint/语法检查相关错误与规范问题	`@Linter Errors`，提问「帮我修复所有 ESLint 错误」
Web	让 AI 自动联网搜索最新资料，作为上下文，答案更实时准确	`@Web`，提问「帮我查一下 React 19 的最新特性」

案例：用 @ 命令精准 Debug

你遇到一个报错：

TypeError: Cannot read properties of undefined (reading 'map')

按 @Terminals 粘贴完整报错日志
按 @Files & Folders 选中报错对应的文件
提问：「帮我定位这个错误的原因，并修复它」 AI 会结合日志和代码上下文，精准定位到：

错误原因：userList 是 undefined，你尝试调用它的 map 方法。修复方案：给 userList 一个默认空数组：
const userList = props.userList || [];
userList.map(user => <div key={user.id}>{user.name}</div>);

九、代码库索引：让 AI 真正理解你的项目

1. 索引原理

Cursor 会为你的项目生成向量嵌入（Embeddings），将代码转换为向量形式，让 AI 能全局理解项目结构、依赖关系、函数调用链，而不是只看当前文件。

2. 索引管理

查看状态：设置 → Indexing，查看索引进度和状态
删除索引：点击 Delete Index 删除并重建索引，解决索引异常问题
暂停索引：点击 Pause Indexing 暂停索引，节省性能

3. 大型项目优化

.cursorignore 文件：在项目根目录创建 .cursorignore，忽略不必要目录（如 node_modules、dist、mock 等），减少索引体积和时间
模块化索引：只索引业务目录，通过 .cursorignore 排除无关内容
团队统一规范：共享 .cursorignore 文件，保证团队索引一致性

案例：你的 .cursorignore 文件：

node_modules/
dist/
build/
mock/
*.log

这样 Cursor 只会索引你的业务代码，大幅提升索引速度和准确性。

4. 价值

快速理解大型项目：AI 能跨文件解释代码逻辑、依赖关系
更精准的补全：基于项目全局上下文，补全更符合业务逻辑
高效重构：跨文件重构时，AI 能识别所有依赖并给出完整方案

十、Rules 规则：团队级提示词工程

Rules 是 Cursor 的高级提示词工程能力，让 AI 遵循团队规范、编码风格、业务逻辑，实现「AI 输出即符合规范」。

1. 规则位置

项目规则：项目根目录 .cursor/rules/xxx.mdc，仅对当前项目生效
全局规则：用户目录下的 .cursor/rules/xxx.mdc，对所有项目生效

2. 编写方式

使用 Markdown 编写
可通过 @file 引用其他规则文件，实现规则复用
可定义：命名规范、注释规范、组件写法、请求封装、错误处理等

案例：.cursor/rules/typescript.mdc

# TypeScript 编码规范
1. 所有变量、函数、类必须使用驼峰命名法
2. 接口名必须以 I 开头，如 IUserInfo
3. 函数必须添加 JSDoc 注释，包含参数、返回值说明
4. 避免使用 any 类型，优先使用 unknown 或具体类型
5. 组件 Props 必须定义为接口，如：
   interface ButtonProps {
     text: string;
     onClick: () => void;
     disabled?: boolean;
   }

当你让 AI 生成代码时，它会自动遵循这些规范。

3. 作用

团队代码风格统一：AI 输出直接符合团队规范，无需二次修改
沉淀团队最佳实践：将团队的编码经验、业务逻辑固化为规则，新人也能快速写出符合要求的代码
提升代码质量：AI 会在生成代码时自动检查是否符合规则，提前发现问题

十一、总结与最佳实践

核心工作流

日常编码：Tab 补全 + 内联聊天（Cmd + K/L），快速实现需求
复杂问题：@ 命令添加上下文 + Chat 对话，精准 Debug 和重构
大型项目：代码库索引 + Rules 规则，让 AI 理解项目并遵循规范
团队协作：@Branch (Diff with Main) 生成 PR 描述，统一 .cursorignore 和 Rules

最佳实践

先写注释再写代码：用清晰的注释描述需求，让 Tab 补全更准确
善用 @ 命令：复杂问题一定要添加上下文，避免 AI 瞎编
定期清理索引：大型项目定期重建索引，保证索引准确性
沉淀团队规则：将团队规范固化为 Rules，让 AI 成为团队的「编码规范执行者」

Cursor 编辑器高效开发完全指南