Cursor AI 编辑器完全指南 - 革命性的 AI 代码编辑器

Cursor AI 是一款革命性的 AI 驱动代码编辑器，基于 VS Code 构建，集成了强大的人工智能功能，可以显著提升开发效率和代码质量。本指南将从基础概念到实际配置，全面介绍如何高效使用 Cursor AI。

一、Cursor AI 简介

1、什么是 Cursor AI？

Cursor AI 是基于 Visual Studio Code 构建的 AI 驱动代码编辑器，由 Anysphere 公司开发。它不仅保留了 VS Code 的所有优秀特性，还深度集成了多种先进的 AI 模型，为开发者提供智能化的编程体验。

2、主要特点

VS Code 兼容性：完全兼容 VS Code 插件生态系统
多模型支持：集成 GPT-4、Claude、Gemini 等多种 AI 模型
智能上下文理解：自动理解整个代码库的结构和逻辑
多模态交互：支持文本、图像等多种输入方式
实时协作：支持团队级别的 AI 协作功能

3、核心功能概览

智能代码补全：Tab 功能提供多行预测和智能重写
AI 对话助手：Chat 模式提供代码解释和建议
自动代码生成：Composer/Agent 模式直接生成和修改代码
终端命令执行：AI 可以自动生成和执行终端命令
上下文感知搜索：智能理解代码库结构，提供精准建议
重构优化：对现有代码进行重构和优化
错误修复：自动检测并修复代码错误

二、核心功能详解

1、快捷键

Ctrl/Cmd + L 打开聊天面板
编辑器：
- 修改代码：选择代码后，使用 Cmd + K 快捷键进行修改
- 生成新代码：在空白处使用 Cmd + K 快捷键生成新代码
- 发送到聊天：使用 Cmd + L 将选中的代码发送到聊天
- 新建聊天: Cmd + N
- 模型切换: Cmd + Option + /
- 聊天切换：上一个聊天Cmd + [、上一个聊天Cmd + ]
- 关闭聊天：Cmd + W
- 消息切换：Tab 切换到下一条消息、Shift + Tab 切换到上一条消息

终端：使用 Cmd + K 在底部打开提示栏
取消AI生成： Cmd + Shift + Delete
接受所有更改：Cmd + Enter
拒绝所有更改：Cmd + Delete

其他

Cmd + Shift + J 打开Cursor Setting
Cmd + , 打开通用设置
Cmd + Shift + P 打开命令面板

更多快捷键，参考 Cursor编辑器 / 快捷键

2、Tab 智能补全

多行预测：预测接下来多行代码的编写
智能重写：自动修正代码错误和不规范写法
光标预测：预测光标的下一个最佳位置
上下文感知：基于最近修改提供相关建议
配置选项：可调整补全的激进程度和触发条件

设置	描述
Cursor Tab	基于最近编辑的上下文感知多行建议，围绕您的光标位置
Partial Accepts	通过 `Cmd →` 接受建议的下一个单词
Suggestions While Commenting	在注释块内启用 Tab
Whitespace-Only Suggestions	允许仅影响格式的编辑
Imports 为 TypeScript	启用自动导入
Auto Import for Python (beta)	为 Python 项目启用自动导入

3、AI 智能体（聊天窗口）

3.1 聊天窗口

窗口管理：

新增上下文：通过 @ 符号或拖拽文件添加
切换上下文：点击 Tab 在不同的上下文集合间切换
历史记录：（时钟符号）查看和管理Agent过去的聊天对话
- 注意：后台Background代理聊天不在常规历史记录中，而是存储在远程数据库中（使用⌘ + E来查看）

聊天窗口核心功能：

检查点（Agent对代码库更改的自动快照）：点击之前请求上的Restore Checkpoint按钮，撤销 Agent 的修改
导出Agent聊天记录：点击上下文菜单 → “Export Chat”
复制/分叉聊天：从对话中的任意点创建分支，以探索替代解决方案，而不会丢失当前对话
- 操作：点击消息上的三个点 / 选择”Duplicate Chat”
Todos规划：Agent 自动为复杂任务创建待办事项列表

实际使用示例

# 代码解释请求
@component.tsx 解释这个组件的工作原理

# 文档查询
@Web React 18 的最佳实践是什么？

# 多文件分析
@src/utils @src/components 这两个模块之间的依赖关系如何？

3.2 选择AI 工作模式

工作模式简述：

Agent 模式：最智能和自主的模式。AI 可以主动选择上下文和使用工具、能够执行复杂的多步骤任务，可以访问终端、搜索代码库、创建和修改多个文件、具有"推理"能力，可以制定和执行计划
- 场景：多个文件的复杂重构、从零到一的完整功能模块开发、跨文件分析和修复bug的复杂调试、项目结构调整和代码分析 —— 重点"跨文件"
Ask 模式：主要用于问答和解释、可以搜索代码库获取上下文、不会主动修改代码、专注于提供信息和建议
- 场景：非常适合在修改代码之前理解代码。理解某段代码的工作原理、项目中的设计模式或架构、查找特定功能的实现位置、实现某个功能的建议、文档查询和最佳实践
Manual 模式（1.0版本）：传统的编辑器模式、AI 功能被限制，主要依赖手动编程、保持对代码的完全控制、类似于普通的 VS Code 体验
- 场景：完全手动控制的精细代码修改、安全敏感或关键业务逻辑、简单的代码修改、审查代码
Background Agents（1.3版本新增）：后台运行的智能助手、持续监控代码质量、自动优化和建议、云端处理能力。
- 场景：持续代码质量监控、自动化优化建议、后台分析和改进

选择策略：

从大到小：复杂任务用 Agent，问答用 Ask，简单编辑用 Manual
根据自主性：需要 AI 主动行动则选 Agent；需要信息则选 Ask；需要完全控制选 Manual
根据影响范围：多文件操作用 Agent，单文件查询用 Ask，局部编辑用 Manual

工作流建议：

项目开始 → Agent 模式（架构设计、基础代码）
↓
开发过程 → Ask 模式（疑问解答、方案咨询）
↓
精细调试 → Manual 模式（精确控制、最终优化）

4、规则

规则为Agent和内联编辑，提示提供持久的、可重用的一致性上下文，用于生成代码、解释编辑或协助工作流程。

注意：Cmd + K 不会应用【项目规则】的上下文

支持三种类型的规则

项目规则：存储在 .cursor/rules 中，受版本控制并作用于你的代码库。
用户规则： Cursor Settings → Rules中设置全局偏好设置，始终应用于你的 Cursor 环境。
.cursorrules（旧版）：仍然支持，但已弃用。请改用项目规则。

4.1 项目规则

*.mdc 本身就是md文档，加上一些自己的语法

使用Cursor Settings > Rules，会在项目根目录下创建.cursor/rules/xxx.mdc格式的项目规则。项目规则的作用：

编码关于代码库的领域特定知识
自动化项目特定的工作流程或模板
标准化样式或架构决策

最佳实践

好的规则应该是专注的、可操作的和有明确范围的
保持规则在500行以内
将大型规则拆分为多个可组合的规则
提供具体的示例或引用文件
避免模糊的指导。编写规则时要像清晰的内部文档一样
在聊天中重复提示时重用规则

4.1.1 规则结构

I. 规则

规则以.mdc编写，核心元数据：description、globs、alwaysApply。下面是与 UI 下拉选项的对应关系：

UI 选项	规则类型	触发时机	关键字段
Always Apply	Always	始终包含到模型上下文,无论何时都会生效	`alwaysApply: true`
Apply Intelligently	Agent Requested	由 AI 判定是否需要	`alwaysApply: false` 且需 `description`
Apply to Specific Files	Auto Attached	引用匹配 `globs` 的文件时自动包含	`globs` 列表、`alwaysApply: false`
Apply Manually	Manual	仅在聊天中 `@规则名` 时包含	`alwaysApply: false`

.mdc 通用模板：

---
description: 用一句话概述这条规则做什么
globs:
  - path/pattern/**/*
alwaysApply: false
---

- 列出应遵循的要点
- 可以多条

@some-file-or-template.ext

示例（整理版）：

---
description: 内部 RPC Service 规范
globs:
alwaysApply: false
---

- 使用内部 RPC 模式定义服务
- 服务名一律使用 snake_case

@service-template.ts # 引用文件在规则触发时作为额外上下文包含

若选择“Apply Manually”，需在对话中 @规则名 才会包含。
选择“Apply to Specific Files”时应补充 globs，引用匹配文件即自动启用。
选择“Always Apply”则将 alwaysApply 设为 true。

II. 规则场景示例

几种规则类型汇总与适用场景：

Always（总是）：规则始终注入到所有对话中，适合“团队必须遵守的核心规范”。
- 适用场景：通用编码规范（代码风格、命名、安全）、文档格式约定、项目全局约束
- 示例：禁止硬编码密钥；统一使用 TypeScript；React 组件命名与导出规范
Auto Attached（自动附加）：当引用到匹配 globs 的文件时才包含，减少不必要的规则负载。
- 适用场景：与文件类型/路径强相关的实践与模板
- 示例：*.test.ts 中的测试风格；/api/** 的 RESTful 设计规范；某技术栈的 hooks 使用准则
Agent Requested（代理判断）：只有在智能体认为需要时才会包含，适合“需要深入思考的高级模式或架构决策”。
- 适用场景：复杂任务的分解策略、性能优化手段、系统设计原则
- 示例：微服务架构设计原则；复杂算法优化策略；数据库设计模式
Manual（手动）：必须在对话中 @规则名 明确提及才包含，适合“新规、敏感或仅作参考的材料”。
- 适用场景：部署/安全清单、非常见或实验性的写法指南、临时作业说明
- 示例：特定客户的定制要求；实验性的新框架使用规范；安全审计检查清单

项目初期推荐配置（建议）：

Always：基础编码规范与项目约定
Auto Attached：文件类型相关规则（测试、API、组件等）
Agent Requested：架构/复杂设计类指引
Manual：特殊需求与参考文档

团队协作最佳实践：

Always → 团队必须遵守的核心规范
Auto Attached → 智能上下文附加的领域规则
Agent Requested → 复杂决策支持
Manual → 灵活的参考资源

4.1.2 嵌套规则

在整个项目的 .cursor/rules 目录中组织规则。当引用其目录中的文件时，嵌套规则会自动附加。

project/
  .cursor/rules/        # 项目范围的规则
  backend/
    server/
      .cursor/rules/    # 后端特定规则
  frontend/
    .cursor/rules/      # 前端特定规则

4.1.3 生成规则

当代理行为做出决策，你希望从聊天中生成项目规则。使用 /Generate Cursor Rules 命令直接在对话中生成规则

4.2 用户规则

在 Cursor Settings → Rules 中定义的全局偏好设置，适用于所有项目。它们是纯文本格式，适合设置首选的沟通风格或编码约定.

1. 请使用中文回答问题。
2. 请保证最小化改动代码。

5、记忆（1.3.0新增）

记忆是基于你在聊天中的对话自动生成的规则。作用范围限定在你的项目内，并在会话之间保持上下文。

当您明确要求 Agent 记住某些内容或当它注意到应该为未来会话保留的重要信息时，Agent 可以直接使用工具调用创建记忆。

Memory created生成或Memory updated更新记忆
View Memories 查看记忆

管理记忆：Cursor Setting → 规则中管理记忆：窗口管理

三、上下文

1、代码库索引`Codebase Indexing`

当你打开一个项目时，Cursor自动为每个文件计算嵌入向量，来索引代码库。目的是为了提高 AI 生成的和你代码相关的答案质量。

检查索引状态：Cursor Settings > Indexing & Docs。如上图中【1】位置
默认索引新文件：图中【位置2】-> Index New Folders。新增文件会增量索引
查看已索引的文件: 图中【位置2】-> Ignore Files in .cursorignore -> View included files，会打开一个列出所有已索引文件的 .txt 文件。
忽略文件：忽略文件（例如 .gitignore、.cursorignore、.cursorindexingignore）中指定的所有文件，不会被索引。
- .cursorignore: 图中【位置2】-> Ignore Files in .cursorignore
- 使用.cursorindexingignore仅从索引中排除文件。文件仍可被 AI 功能访问，但不会出现在代码库搜索中。
- 全局忽略文件：Cmd + ,(用户设置) -> 搜索： Global Cursor Ignore List，设置所有项目的忽略模式
- 其他默认的忽略文件，参考：Cursor上下文/忽略文件
团队仓库控制范围：图中【位置2】-> Team-Level Repository Control。团队设置仓库范围的控制模式，用于确定哪些文件包含在索引中

2、`MCP`

Model Context Protocol (MCP)使 Cursor 能够连接到外部工具和数据源。

MCP服务器：Cursor文档 / MCP服务器

添加 MCP 到 Cursor: 项目中创建 .cursor/mcp.json 用于项目特定的工具。或在主目录中创建 ~/.cursor/mcp.json 全局工具的配置

{
  "mcpServers": {
      "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
          "API_KEY": "value"
      }
      }
  }
}

3、`@`符号

常用功能：

@Files文件名 - 引用项目中的特定文件
@Folders - 引用整个文件夹以获得更广泛的上下文
@Code - 引用代码库中的特定代码片段或符号
@Past Chats - 引用其他标签页或之前会话的上下文(聊天记录)
@Cursor Rules - 使用 cursor 规则
@Docs - 访问文档和指南
@Web - 搜索外部网络资源和文档
@LibraryName - 引用流行库的官方文档

其他功能：

@Git - 访问 git 历史记录和更改
@Link (paste) - 创建指向特定代码或文档的链接，并获取内容作为上下文使用。
- 要将URL用作纯文本而不获取其内容：
  - 方式1：点击标记的链接并选择Unlink
  - 方式2：在粘贴时按住Shift 键，以防止自动标记
@Recent Changes - 将最近的10次（时间顺序）代码更改，作为上下文包含在 AI 对话中
@Lint Errors - 自动捕获并提供当前活动文件中，代码检查错误和警告的上下文信息
# Files - 将文件添加到上下文中而不引用
/command - 支持添加"激活的文件"（编辑器中已打开标签页）到上下文中
- /Reset Context: 将上下文重置为默认状态
- /Generate Cursor Rules: 为 Cursor 生成要遵循的规则
- /Disable Iterate on Lints: 不会尝试修复代码检查错误和警告
- /Add Open Files to Context: 引用当前打开的所有编辑器标签页
- /Add Active Files to Context: 引用当前视图中的所有编辑器标签页（在分屏布局中很有用）

四、模型`Models`

1、基础概念：上下文窗口

上下文窗口是LLM一次可以共同考虑的最大token范围（包含输入与模型输出）。在 Cursor 中，默认可用约 200k tokens（约 1.5 万行代码）；开启 Max Mode 可将上下文扩展到所选模型的最大上限，但速度更慢、成本更高。

2、模式选择

Max Mode：将上下文扩展到模型上限，适合跨仓库/跨多文件的大型重构、复杂架构设计、长文档推理；权衡是更慢、更贵。
Auto：由 Cursor 按任务自动选择更合适的高级模型，适合日常开发与通用场景；权衡是偶尔不够“稳”。

3、任务-模型选型建议

可用模型列表:

Claude-4-Sonnet：Anthropic 的旗舰模型，擅长代码生成
o3：OpenAI 的推理模型，适合复杂问题解决
Gemini-2.5-Pro：Google 的多模态模型
GPT-4.1：OpenAI 的通用模型
Claude-3.7-Sonnet：平衡性能和成本的选择
Cursor-Small：Cursor 自有模型，无限制使用
o4-Mini：轻量级快速响应模型

模型选择建议：

高复杂度任务：使用 Max Mode 搭配 o3 / Claude 4（复杂架构、算法/设计）
中等复杂度任务：Claude 3.5 / GPT-4.1（常规开发、重构）
轻量/快速任务：Auto 模式（代码补全、局部小改动）

模型使用提示：

带 🧠 脑洞图标的大模型：表示具有高级推理能力的模型；适用于复杂逻辑推理、数学计算、架构设计，常消耗更多 tokens
高级模型：Claude / GPT-4o（会扣除“快速调用”的次数）
轻量模型：cursor-small、o4-mini（适合 Cmd + K、函数级优化、行内修改）
模型侧重：Claude 更擅长代码推理与重构；GPT-4o 更擅长通用问答与多媒体理解
局部修改优先小模型；若输出不稳定，可切换 Auto 或较新的大模型
追求稳定与一致性：优先选择最新可用模型版本

注意：Cursor AI 持续快速发展，功能和界面会不断更新。建议定期查看官方文档获取最新信息，并根据实际需求调整使用策略。

附录

设置Cursor工具栏方向

Cursor设置（快捷键Cmd + ,） -> 搜索 Workbench › Activity Bar: Orientation，选择 vertical

常用的`Cursor Settings`（1.3.0）

`Cursor Tab`

`Cursor Chat`

默认模式 Default Mode（Agent）：新会话默认 Agent；写长文/精准改写可切 Composer。
默认位置 Default Location（Pane）：在侧边面板打开；需要在编辑器区域打开用 Editor。
文本大小 Text Size（Default）：调整聊天字体；演示时调大一档。
自动清理会话 Auto-Clear Chat（开启）：当一段时间未在聊天窗操作时，下次打开聊天窗会自动新建一个会话。旧会话不会被删除，仍可在历史里打开。如果你需要持续上下文，则关闭。
自动滚动到新消息 Scroll to New Messages（开启）：新回复自动滚动到底部，建议保持。
完成音效 Completion Sound（关闭）：回复完成提示音；需要提醒时再开启。
待办清单 To-Do List（开启）：允许跟踪任务进度，长任务建议开启。
消息排队 Queue Messages（开启）：流式回复排队防乱序；需要即时打断时可关闭。
自定义模式 Custom Modes（开启，Beta）：可建模型/工具/指令预设；建议建"重构TS/写文档/单测生成"等。

Context上下文

Include Full-Folder Context（开）：将文件夹内所有文件纳入上下文，便于全局理解，但更耗资源。
Web Search Tool（开）：允许联网查询补充信息，涉及隐私时可关闭。
Hierarchical Cursor Ignore（关）：让 .cursorignore的忽略规则向下继承，作用到所在目录的所有子目录与文件。切换该开关后需要重启 Cursor 生效。
Backspace Removes Context（开）：当光标在输入框“最开头”时，按下Backspace / Delete不会删文字，而是“弹出”最后一个上下文胶囊（context pill）。相当于用键盘快速移除最近添加的上下文，按一次删一个，顺序是后进先出。

Applying Changes应用变更

Out-of-Context Edits in Review Mode（开）：Review Mode模式下，允许修改不在当前选中上下文/文件列表的其他文件。即许跨文件、跨目录地联动修改。
Auto-Fix Lints（开）：自动应用可修复的 Lint 规则
Auto-Accept on Commit（关）：文件提交时，自动接受聊天中的变更

Auto-Run自动执行配置

Auto-Run Mode（开）：允许 Agent 在无需确认的情况下，执行命令、写文件。适用于连续构建/测试/重构等流水作业，但存在误执行风险。
Command Allowlist（空）：白名单内的命令可被自动执行；未在名单内的命令仍需确认。开启自动运行时务必配置白名单，只放安全、幂等命令。
```
npm ci
npm run build
go test ./...
```
File-Deletion Protection（关）：阻止 Agent 自动删除文件。关闭状态风险较高，团队项目建议开启。
MCP Tools Protection（关）：阻止 Agent 自动调用 MCP 工具。关闭可能触发外部副作用，生产环境建议开启。
Dotfile Protection（开）：阻止自动修改点文件（如 .gitignore、.npmrc）。避免全局配置被意外改动，建议保持开启。
External-File Protection（开）：阻止在工作区外创建/修改文件。防止越权写入，强烈建议保持开启。

Inline Editing行内编辑器 & Terminal终端配置

工具栏高亮 Toolbar on Selection（开）：选中代码时显示“Add to Chat/Quick Edit”快捷按钮，建议开启。
自动解析链接 Auto-Parse Links（关）：自动将粘贴到输入框中的URL转为上下文，担心隐私时保持关闭。
自动选区 Auto-Select Code Regions for Quick Edit（开）：Cmd + K时，自动框定代码（模）块，建议开启。
主题化差异背景 Themed Diff Backgrounds（开）：使用主题色背景显示差异，建议开启。
字符级差异 Character-Level Diffs（开）：显示具体字符变更高亮，建议开启。
终端提示 Terminal Tooltips（开）：终端显示"Add to chat"等提示，建议开启。
终端快捷提示 Terminal Hint（开）：终端提示可用⌘K，建议开启。
终端预览框 Preview Box for Terminal ⌘K（关）：AI回复先在预览框展示，避免命令直接流入shell执行，安全需求时可开启。

`Background Agents` 后台代理（精简）

是什么：在云端长期运行的代理，用于代码审查、开分支改动、开PR、通知协作（Beta）。
前提条件：
- 需开启 Background Agents 并配置按量计费；
- 必须连接 GitHub 仓库（当前版本Cursor@1.3.0标注Required）；
- Slack 为可选，仅用于消息协作与通知。
国内团队常见问题：
- 仅有GitLab、无GitHub：暂不支持完整云端代理流程（如自动开PR）。可将仓库镜像到GitHub作为代理入口，或改用本地Agent工作流并在GitLab手动发MR。
- 非Slack：不影响核心能力，Slack只是可选集成。

`Rules & Memories`

Rules
- Include .cursorrules file（开）: 打开后，当前项目根目录下的.cursorrules（旧版）会被自动附加到每次请求中，作为“项目级规则”。关闭则完全忽略该类文件。

`Network`

HTTP Compatibility Mode：默认且推荐使用HTTP/2（流式更快、延迟更低）。在公司代理/VPN 等环境下若出现“连接中/流式中断/HTTP2 protocol error”等，切换为HTTP/1.1并重启 Cursor。
Network Diagnostics：点击Run Diagnostic做连通性自检，记录失败的域名/步骤，交给网络/安全团队放行（通常 443/TLS）。

参考资源

最后，希望大家早日实现：成为编程高手的伟大梦想！
欢迎交流~

本文版权归原作者曜灵所有！未经允许，严禁转载！对非法转载者, 原作者保留采用法律手段追究的权利！
若需转载，请联系微信公众号：连先生有猫病，可获取作者联系方式！

一、Cursor AI 简介#

1、什么是 Cursor AI？#

2、主要特点#

3、核心功能概览#

二、核心功能详解#

1、快捷键#

2、Tab 智能补全#

3、AI 智能体（聊天窗口）#

3.1 聊天窗口#

3.2 选择AI 工作模式#

4、规则#

4.1 项目规则#

4.1.1 规则结构#

I. 规则#

II. 规则场景示例#

4.1.2 嵌套规则#

4.1.3 生成规则#

4.2 用户规则#

5、记忆（1.3.0新增）#

三、上下文#

1、代码库索引Codebase Indexing#

2、MCP#

3、@符号#

四、模型Models#

1、基础概念：上下文窗口#

2、模式选择#

3、任务-模型选型建议#

附录#

设置Cursor工具栏方向#

常用的Cursor Settings（1.3.0）#

Cursor Tab#

Cursor Chat#

Background Agents 后台代理（精简）#

Rules & Memories#

Network#

参考资源#