Cursor 上手指南

Cursor 是 Anysphere 出品的 AI 代码编辑器，本质是 VS Code 的一个深度定制分支（fork）——保留你熟悉的编辑器体验，但在底层重构了 AI 能力，让模型能够理解整个代码库上下文，而不只是补全当前文件。

一句话定位：Cursor = VS Code + 深度集成的代码库级 AI Agent。如果 VS Code 是「记事本」，Cursor 就是「能看懂整个项目、还能替你动手改的记事本」。

一、安装与环境准备

访问 cursor.com 下载对应平台版本，安装后做三件事：

导入 VS Code 配置：命令面板（Cmd+Shift+P / Ctrl+Shift+P）执行 Import VS Code Settings，可一键迁移快捷键、插件和主题，迁移成本极低。
配置 .cursorignore：在项目根目录创建 .cursorignore，排除 node_modules/、dist/、.next/、.turbo/ 等目录，避免索引无关文件导致 CPU 占用飙升。
确认代码库索引完成：Settings → Features → Codebase Indexing，状态应显示 Indexed。

二、四种核心工作方式

Cursor 的 AI 能力可以归纳为四类，按「介入程度」由浅入深。

1. Tab 补全：最频繁的日常助手

Tab 补全由轻量模型（cursor-small）驱动，延迟通常低于 200ms。它不只是补全当前行，还能：

预测你下一步要改哪里（多位置编辑提示）
根据上下文理解意图，补全整段逻辑
按 Tab 接受、Esc 拒绝

2. Cmd+K：内联编辑

选中代码后按 Cmd+K（Windows：Ctrl+K），用自然语言描述想做的修改，改动就地生成、可预览 diff：

"把这个函数改成 async/await 写法"
"给这段循环加上边界检查"
"提取成独立工具函数并补上单测"

3. Chat 面板（Cmd+L）：三种模式

打开 Chat 面板后，可在底部切换三种模式：

模式	行为	适用
Ask	只回答问题，不改代码	读懂陌生代码、定位逻辑
Edit	对指定文件做定向修改	小范围、明确的改动
Agent	自主规划、跨文件编辑、可跑命令	复杂多文件任务

建议：对不熟悉的代码，先用 Ask 模式问清「认证逻辑在哪、这段 reducer 做什么」，再切 Agent 动手，比直接盲改效率高得多。

4. Agent 模式（Cmd+I，原 Composer）

Agent 是 Cursor 的自主工作流：描述一个「结果型」任务，它会自己读代码、定位文件、执行修改、跑终端命令、看输出并迭代，直到完成。

"给登录接口加一个限流器，并补一个能证明它生效的测试"
"把 user.service 和 order.service 里的查询统一改成 Prisma"

Plan Mode（规划模式）：在 Agent 输入框按 Shift+Tab 切换。开启后 Agent 先不写代码，而是调研代码库、产出带文件路径和引用的实施计划，等你确认后再动手。计划可「Save to workspace」存入 .cursor/plans/，便于团队协作与后续续作。

三、上下文引用：@ 的力量

在 Chat/Agent 中用 @ 精确圈定上下文，是让输出质量显著提升的关键：

@Codebase — 语义搜索整个代码库
@Files / @Folders — 引用特定文件/目录
@Web — 联网检索最新文档
@Docs — 引用你添加的第三方文档（Settings → Features → Docs 配置）
@Git — 查询提交历史（如「最近 3 次提交关于认证改了什么」）
@Notepad — 引用持久化便签（见下文）

四、项目规则：从 `.cursorrules` 到 `.cursor/rules/`

这是 2026 年最重要的变化：旧的根目录 .cursorrules 单文件已弃用，取而代之的是 .cursor/rules/ 目录下的模块化 .mdc 规则文件。

.mdc 文件通过 frontmatter 控制生效时机：

markdown

---
description: "Next.js API 路由规范"
globs: ["app/api/**/*.ts"]
alwaysApply: false
---
## API Route 约定
- 用 Route Handler（不用 pages/api）
- 校验请求体用 Zod
- 返回统一错误结构 { error: string, code: string }
- 数据库用 lib/db.ts 单例，禁止直接 new PrismaClient

三个关键配置项：

配置	作用
`alwaysApply: true`	每次请求都注入（放高层上下文，如技术栈、项目目标、No-Go 区）
`alwaysApply: false`	由 Cursor 根据 description 智能判断是否加载
`globs: [...]`	仅当编辑的文件命中 glob 时生效（最省 token）

实践建议：建一个 project-context.mdc（alwaysApply: true）写清技术栈、目录结构、迁移中的技术方向等「事实真相」，避免模型臆造；其余规则按文件类型拆分成多个 globs 作用域的 .mdc。规则应提交进 Git，兼作团队编码规范文档。

五、进阶配置：Commands / Skills / Subagents

Cursor 已移除旧的 Custom Modes，改为三类可扩展机制：

Slash Commands（.cursor/commands/*.md）：把一段固定提示词 + 规则引用打包成 /xxx 触发，如 /review 一键触发代码审查。
Skills（.cursor/skills/）：给 Agent 提供可执行工具（脚本、文档拉取等），不只是文本指令。
Subagents（.cursor/agents/）：独立上下文窗口的子代理，用于规划、架构分析等重推理任务，不污染主对话。

此外还有两个实用的上下文特性：

Notepads：持久化便签，可 @Notepad 附加到任意会话，适合跨会话记住架构决策、迭代目标等临时上下文（区别于「规则」，规则管约定、便签管会话上下文）。
Background Agents（beta）：Agent 任务可「Run in background」后台执行，完成后通知，适合无需实时盯着的长任务。

六、模型选择

Cursor 支持按任务切换模型，也可自带 API Key：

模型	适用
Claude Sonnet 4.x（默认）	日常编码、Agent 复杂多文件任务，最均衡
Claude Opus 4.x	疑难 bug、复杂架构决策
GPT-5.x	快速 agentic 编辑、联网搜索
Gemini 2.5/3.x Pro	超长上下文分析
cursor-small	Tab 补全（内置，极快）

模型清单以 Cursor 内置的 model picker 为准，随版本持续更新。

七、定价与隐私

版本	价格	说明
Hobby	免费	约 50 次 Agent 请求/月，适合试用
Pro	$20/月	约 500 次 Agent 请求/月，全模型、可开 Privacy Mode
Business	$40/人/月	无限（公平使用），SSO、组织级隐私管控

隐私提示：默认情况下 Cursor 会用你的代码改进模型。敏感项目务必开启 Settings → General → Privacy Mode，禁用代码用于训练（Business 版可组织级强制开启）。

八、上手建议

先规则后编码：第一天就写好 .cursor/rules/，否则模型会用通用模式生成、偏离你的代码库。
先问后改：陌生代码先用 Ask 模式 + @Codebase 摸清，再交给 Agent。
Agent 只用于多文件/复杂任务：一行代码的改动直接手改，Agent 的规划/执行开销只在复杂场景才划算。
改完必审：在 Source Control 面板核对 diff，确认没被「好心」多改，导入的包名是否真实存在。
警惕过度预测：Tab 补全与 Agent 都可能越界，AI 生成的代码务必人工 review。

Cursor 上手指南 ​

一、安装与环境准备 ​

二、四种核心工作方式 ​

1. Tab 补全：最频繁的日常助手 ​

2. Cmd+K：内联编辑 ​

3. Chat 面板（Cmd+L）：三种模式 ​

4. Agent 模式（Cmd+I，原 Composer） ​

三、上下文引用：@ 的力量 ​

四、项目规则：从 .cursorrules 到 .cursor/rules/ ​

五、进阶配置：Commands / Skills / Subagents ​

六、模型选择 ​

七、定价与隐私 ​

八、上手建议 ​

相关资源 ​