Cursor 使用教程：从安装配置到 Agent 自主编程的完整指南

如果你还在用「让 ChatGPT 写代码然后手动粘贴」的方式工作，这篇文章可能会改变你的习惯。

Cursor 不是代码自动补全工具，也不是一个 ChatGPT 插件——它是一个以 AI 为核心重新设计过交互方式的代码编辑器。从第一次 Tab 补全接受一整个函数，到用自然语言让 AI 独立完成一个功能模块并跑通测试，这中间有一套完整的使用逻辑。

这篇文章从安装开始，把 Cursor 的每个核心功能和使用场景讲清楚，最后以一个实际项目贯穿演示。

---

Cursor 是什么

Cursor 是基于 VS Code 深度魔改的编辑器，所有的快捷键、插件、配色方案都和 VS Code 完全兼容——如果你有 VS Code 的使用习惯，切换过来几乎没有学习成本，区别只在于多了一套强大的 AI 层。

和「IDE 里装个 Copilot 插件」的方案相比，Cursor 的核心差异在于：

• AI 对整个代码库有感知：不是只看当前文件，而是理解项目结构、文件依赖关系、你写过的函数命名习惯
• 多种协作模式：补全、对话、指令改写、Agent 自主完成——针对不同任务密度有对应工具
• Rules 系统：可以给项目写「AI 指令书」，规定技术栈、代码风格、命名规范，让 AI 在整个项目中保持一致

---

安装与基础配置

安装

从 cursor.com 下载对应平台的安装包（Windows / macOS / Linux），安装后首次启动会提示导入 VS Code 配置，选「是」即可把插件、主题、快捷键全部迁移过来。

选择模型

设置（Ctrl+Shift+J）→「Models」，可以切换 AI 的底层模型。主要选项：

模型	特点	适用场景
claude-4-sonnet	综合质量最好，逻辑强	复杂功能、架构设计、代码审查
gpt-4.1	速度快，代码质量稳	日常补全、快速改写
claude-4-haiku	极快，成本低	简单任务、高频补全
gemini-2.5-pro	上下文窗口大	超大代码库、长文件分析

没有特别要求的话，claude-4-sonnet 是综合最优的日常选择。

设置 .cursorrules（现在叫 Rules for AI）

在项目根目录创建 .cursor/rules 文件夹，新建一个规则文件（比如 main.mdc）。这是整个项目的「AI 宪法」，所有 AI 交互都会遵守这里写的内容：

你是一个 TypeScript + React 项目的助手。

技术栈规范：
- 前端：React 18，TypeScript strict 模式
- 样式：Tailwind CSS，不要写内联样式
- 状态管理：Zustand，不要用 Redux
- 组件命名：PascalCase，文件名同组件名
- 函数命名：camelCase，异步函数以 fetch/load/save 开头

代码规范：
- 所有函数必须有 TypeScript 类型注解
- 不要用 any 类型
- 组件 props 用 interface 定义，不用 type
- 注释用中文

这个文件一旦写好，之后无论在哪个文件里用 AI，它都会自动遵守这些规则，不需要每次重新交代。

---

核心功能详解

Tab 补全：比你想的聪明

Cursor 的补全不是简单的下一词预测。它会看：

1. 当前函数的上下文（参数名、已有逻辑）
2. 同文件中其他函数的写法
3. 你最近几次接受补全的内容（学习你的风格）

常见用法是「先写注释，让 Tab 生成实现」：

// 计算购物车总价，price 已含税，discount 为折扣率（0-1），满 300 打九折

光标放在这行注释下面，Tab 一下，通常能直接生成正确的函数。遇到长函数可以连续多次 Tab，分段接受。

不接受补全的快捷键：Esc。如果补全不对，按 Esc 丢弃，继续手写，Cursor 会从你的手写里重新学习并调整。

Chat 模式（Ctrl+L）：问代码库里的问题

Chat 和普通 ChatGPT 的根本区别是「有代码库上下文」。可以直接问：

• 「这个 useUserStore 在哪里定义的，有哪些地方用到了它？」
• 「为什么 handleSubmit 里没有做 loading 状态管理，其他表单是怎么处理的？」
• 「帮我找一下项目里有没有类似的数据表格组件可以复用」

Chat 里可以用 @ 引用具体的文件、文件夹、甚至 Git 历史，让 AI 聚焦在特定上下文里。

技巧：对话里不要只说「修这个 bug」，要把现象、期望、已经尝试过的方法都说清楚——AI 给出的答案质量和你描述问题的精度成正比。

Cmd+K：在文件里直接改写

选中一段代码，按 Ctrl+K（macOS 是 Cmd+K），输入指令，AI 直接在文件里修改，同时展示 diff 让你确认。

适合的场景：

• 「把这个函数改成 async/await 风格」
• 「给这个组件加上错误边界处理」
• 「把所有 console.log 改成 logger.debug」

Ctrl+K 是文件级别的精准改写，不涉及其他文件，适合快速的局部修改。

Agent 模式（Ctrl+I）：让 AI 自己跑

这是 Cursor 最强力也最需要理解的功能。Agent 模式下，AI 可以：

• 自主创建、修改、删除文件
• 运行终端命令（安装依赖、跑测试）
• 根据执行结果调整下一步操作

使用方式：按 Ctrl+I 打开 Composer，描述你要完成的功能，然后等它工作。

重要心态转变：不要在 Agent 开始后就盯着每一步操作挑毛病。Agent 工作到一半的时候中断它、给它大量即时反馈，反而会让结果变差。给它一个完整清晰的任务描述，让它跑完，然后 code review 结果，指出问题让它修。

Agent 失败的最常见原因：任务描述太模糊。「帮我做一个用户管理系统」这类描述会让 AI 做很多假设，结果可能和你预期差很远。换成「在现有 /api/users 路由下增加一个 PATCH /users/:id 端点，参数是 {name, email}，需要验证邮箱格式，更新 users 表，返回更新后的用户对象，参考 GET /users/:id 的错误处理方式」——这个描述就清晰很多。

---

Rules for AI 进阶用法

除了全局规则，Cursor 支持文件夹级别的规则，以及按情景触发的规则。

场景规则示例：新建一个 test.mdc 规则文件，设定「仅在测试文件里触发」：

当我要求写测试时：
- 使用 vitest，不要用 jest
- 测试文件放在被测文件同目录的 __tests__ 文件夹里
- 每个测试必须包含：正常情况、边界情况、错误情况三种 case
- mock 外部依赖，不要发真实网络请求
- 测试描述用中文

这样当你在 __tests__ 目录里让 AI 写测试时，它会自动应用这套规范；在其他文件里工作时这个规则不生效，不干扰正常开发。

---

实战：用 Cursor Agent 构建一个 Markdown 笔记应用

下面用一个简单的 Markdown 笔记 Web App 演示 Agent 的完整工作流程。目标是：本地 Vite + React + TypeScript 项目，可以新建/编辑/保存/删除笔记，内容以 Markdown 格式存储，支持实时预览。

第一步：初始化项目，写 Rules

pnpm create vite notes-app --template react-ts
cd notes-app
pnpm install

在 .cursor/rules/main.mdc 里写好技术栈规则（见上方示例，把状态管理改成 Zustand，增加 marked 库处理 Markdown 渲染的说明）。

第二步：用 Agent 生成核心数据层

打开 Composer（Ctrl+I），输入：

创建笔记应用的数据层：

1. 在 src/store/notesStore.ts 里用 Zustand 创建笔记 store，笔记有 id（UUID）、title、content（Markdown 文本）、createdAt、updatedAt 字段
2. 实现 actions：createNote、updateNote、deleteNote、setActiveNote
3. 初始化时加载 3 条示例笔记
4. 用 localStorage 持久化数据（zustand persist 中间件）

Agent 会创建文件、安装依赖（uuid、zustand），写出完整的 store。整个过程大概 40-60 秒。

第三步：用 Agent 生成 UI 组件

继续在 Composer 里：

基于 notesStore，创建以下组件：

1. NoteList：左侧笔记列表，显示标题和创建时间，点击切换 activeNote，支持删除
2. NoteEditor：右侧编辑区，textarea 输入 Markdown，实时用 marked 渲染预览（左右分栏）
3. AppLayout：组合 NoteList 和 NoteEditor，顶部有「新建笔记」按钮
4. 样式用 Tailwind，整体配色用深色主题

Agent 会依次创建组件文件，在组件里正确引用 store，装上 marked 库，完成渲染逻辑。

第四步：用 Cmd+K 做局部优化

跑起来之后，发现标题编辑没有 debounce（每次按键都在更新 store）。选中 NoteEditor 里的 title input 处理函数，Ctrl+K：

给标题输入加 300ms debounce，避免频繁更新 store

5 秒生成，确认 diff，接受。

第五步：用 Chat 排查问题

如果 Markdown 渲染里 code block 的代码没有语法高亮，打开 Chat（Ctrl+L）：

@src/components/NoteEditor.tsx Markdown 渲染用的 marked，但代码块没有语法高亮，我想加 highlight.js，怎么改？

Chat 会给出修改方案，还能直接点「Apply to file」把代码应用到文件里。

---

Cursor 与常用工具的集成

Git：Cursor 的 Source Control 面板和 VS Code 一致，对 staged 的改动可以直接在 Chat 里让 AI 「写一个规范的 commit message」，引用 @git diff 上下文。

终端：在 Agent 模式下，AI 可以直接执行终端命令。如果不放心，可以在设置里把 Agent 的终端执行权限设为「需要确认」，每次执行命令前会弹出确认。

MCP（Model Context Protocol）：Cursor 支持通过 MCP 接入外部工具，比如连接数据库直接查表结构、接入 Jira 读取当前 sprint 的 ticket、连接 Figma 读取设计稿尺寸。配置方法：设置 →「MCP Servers」→ 添加对应的 MCP 服务器地址。

---

让 Cursor 发挥最大价值的几个原则

原则一：Rules 写得越细，AI 越省心

最值得投入时间的地方是在项目开始时把 .cursor/rules 文件写好。一个好的 Rules 文件能消除项目里 90% 的「AI 没按我习惯写」的问题。可以从第一个 AI 生成的代码里挑出不满意的地方，逐条加进 Rules 里。

原则二：Agent 适合「一次性功能」，不适合「渐进式迭代」

Agent 最适合「新增一个完整功能」这种任务，比如「做登录页」「写一套 API 测试」「搭建 CI/CD 配置」。如果是「把现有组件改得更好」这种需要大量上下文理解的任务，Chat + Ctrl+K 的组合更可控。

原则三：维护一个「上下文文件」

在大型项目里，可以维护一个 CONTEXT.md 或 AI_NOTES.md，记录项目里一些不在代码里但 AI 需要知道的信息：「UserType 这个 enum 不要改，和后端协议锁定的」「这个 legacyHelper.ts 文件先不动，下个版本统一重构」。然后在 Chat 里 @CONTEXT.md 给 AI 读。

原则四：不要对 AI 的代码「信任但不验证」

AI 生成的代码在通过明显的代码审查后，一定要跑测试或手动验证边界情况。特别是 Agent 生成的代码，很可能在主路径正确但边界处理不完整。把 Review AI 代码当成 Review 实习生代码的心态——不是每行都重写，而是看逻辑是否合理、边界是否覆盖、安全问题有没有漏。

---

常见问题排查

Q：补全经常不出现或者很慢

检查网络是否能访问 Cursor 的服务器（cursor.com 和其 API 端点在境外）。如果使用境外网络，补全速度会明显更快。也可以在设置里切换到更快的模型（claude-4-haiku）。

Q：Agent 做了一半停下来问我

这是正常行为——遇到需要确认的决策（如选择数据库方案、是否覆盖已有文件）Agent 会暂停等待。给出明确答复就能继续。如果不想被打断，在任务描述里提前把关键决策点说清楚。

Q：Chat 上下文太多导致回答开始偏题

长对话里 AI 的注意力会被早期对话稀释。发现答案开始不精准时，点「New Chat」开一个新会话，用 @ 重新引用需要的文件，比继续在旧对话里追问效果好很多。

Q：Cursor 是否比 VS Code + Copilot 强

对于轻度使用（偶尔补全，偶尔让 AI 写个函数）：差别不大。对于重度使用（用 AI 完成完整功能模块、多文件联动修改）：Cursor 的 Agent 模式和 Rules 系统没有等价替代，差距很显著。如果每天有超过 2 小时在写代码，Cursor 的订阅是值得的。

---

FAQ

Q：Cursor 免费版够用吗？

免费版有每月的 AI 请求次数限制（目前 2000 次/月），对轻度使用够用。重度开发用 Pro 版（每月约 20 美元），请求次数更多，还能用最新的模型版本。企业有团队套餐，可以统一管理账号和 Rules。

Q：Cursor 支持哪些编程语言？

理论上支持所有 VS Code 支持的语言。AI 质量最好的是 TypeScript、Python、JavaScript、Go、Rust、Java；对 SQL、Shell 脚本、Terraform 等也有不错支持。小众语言 AI 质量会差一些，但补全和 Chat 仍然可用。

Q：代码会不会被 Cursor 拿去训练模型？

默认情况下，Cursor 不使用用户代码训练模型（根据官方隐私政策）。企业版有「隐私模式」，代码不经过第三方服务器。如果是高度敏感的代码库，建议开启隐私模式并确认当前模型提供方的数据政策。

Q：Cursor 能用来写文档、写测试吗，还是只适合写功能代码？

非常适合写测试和文档。给 AI 一个组件文件，让它写对应的 Vitest 测试，通常能覆盖 80% 的 case，剩下的边界情况自己补。写 API 文档、README、组件 props 说明，也是 AI 省力最明显的场景之一。

Q：已经在用 GitHub Copilot 了，还有必要换 Cursor 吗？

如果你的工作里有「需要跨多文件理解和修改」的任务，比如重构、新建功能模块、修复涉及多处的 bug，换 Cursor 会有明显感知差异。如果以单文件的补全为主，迁移收益不大。建议用 Cursor 的免费版试用两周，主观感受决定要不要换。