跳到主要内容

Cursor IDE 使用指南（从入门到熟练）

TL;DR：Cursor 是一个 VS Code 风格的 AI 编程 IDE，擅长 多文件改动 与 项目级重构。最快的上手路径是：先让项目索引完成 → 固定使用“计划 → 改动 → 验证”的工作流 → 用 Cursor Rules 把团队/项目规范写下来，避免每次重复解释。

你能从这份指南得到什么​

用 15-30 分钟掌握 Cursor 的基础设置、核心工作流和安全改动方式，避免多文件修改带来的风险。

快速上手清单：

  • 安装 Cursor 并打开仓库根目录
  • 等待索引完成再开始提需求
  • 固定使用“计划 → 改动 → 验证”闭环
  • 把规范写进 .cursorrules

我应该用 Cursor 做什么？什么时候不要用？​

Cursor 最适合解决的问题是：需要跨多个文件协调的改动，例如：

  • 新增一个功能：UI + API + 测试同时改动
  • 重构与迁移：统一改名、抽模块、换 API
  • 进入新仓库：让它解释架构、定位入口、找调用链

不太适合（或需要更谨慎）的场景：

  • 安全关键代码（鉴权/权限/加密）：必须人工审查 + 增加测试
  • 一次性大改动（数十文件、上千行 diff）：先拆分任务再做
  • 你没有验证闭环：如果你不跑 lint/typecheck/build，Cursor 会把“看起来对”变成“真实 bug”

一个稳定的 Cursor 工作流长什么样？​

把 Cursor 当成“执行型同事”，你负责把任务变成可验证的步骤。

推荐默认流程：

  1. 写清目标与范围：这次只做什么，不做什么
  2. 让它先读再改：先定位入口、相关文件、风险点
  3. 让它给计划：计划里必须包含“验证命令”
  4. 一次只做一步：做完就停下来跑检查
  5. 复盘并固化：把重复提醒写进 .cursorrules

模板（可直接复制）：

你正在修改一个生产仓库。
目标：完成 [具体功能]。
范围：只改 [A/B/C]，不要改 [X/Y/Z]。
约束：不新增依赖；diff 尽量小；保持现有结构与命名。

请先：
1) 列出你要读的文件
2) 给出 3-5 步计划（每步包含验证方式）
3) 再开始做第 1 步

上下文怎么给才“够用但不浪费”？​

很多“Cursor 不懂我”其实是上下文没给对。你可以用这套原则：

  • 给入口：相关页面/组件/路由/命令从哪里触发
  • 给约束：技术栈、目录结构、风格、禁止事项
  • 给失败信号：现有报错、复现步骤、预期结果
  • 少贴无关文件：优先给最小片段 + 文件路径

如果它找不到符号，直接把这些信息补上：

  • 符号名 + 可能的文件路径
  • import/export 关系（从哪里引用）
  • 你运行时看到的错误/日志

如何用 Cursor 做“可审查”的多文件改动？​

多文件改动的核心是：把 diff 变小、变可预测。建议：

  1. 先让 Cursor 输出“文件清单 + 每个文件改什么”
  2. 先改类型/接口（最容易审查），再改实现，再改调用点
  3. 每一步跑一次验证（lint/typecheck/tests/build）
  4. 最后做清理：删除无用代码、统一命名、补文档

一个实战例子（以 JS/TS monorepo 为例）：

我们要新增一个页面区块，但必须保持 build 通过。
请按顺序：
1) 找到页面入口与数据来源
2) 只新增一个最小组件并接入
3) 提供 pnpm build 的验证步骤
4) 再迭代样式与文案

Cursor Rules（.cursorrules）进阶：把“重复提醒”一次写完​

你每次都在说的那些话（不加依赖、保持 diff 小、跑 pnpm build），都应该写进规则文件。

一个适合通用 monorepo 的起点：

# General
- Keep diffs small and reviewable.
- Prefer editing existing files over creating new ones.
- Do not add new dependencies unless explicitly asked.

# Repo structure
- This repo is a monorepo; changes must target the correct app/package.
- Shared content lives in `content/` (docs/blog/i18n).

# Quality gates
- Always propose verification commands (lint/typecheck/build/tests).
- If unsure, ask clarifying questions before editing.

# Safety
- Never paste or generate secrets.
- Avoid destructive git commands unless explicitly requested.

技巧：把规则写得“可执行”，而不是写成口号。比如“跑 pnpm build”比“注意质量”更有效。

实战：用 Cursor 做一次“安全的小改动”​

下面是一个你可以用来训练工作流的练习（强烈建议做 3 次）：

目标：在一个页面里新增一个区块（文案 + 链接），并确保构建通过。

推荐对话（你可以照着提）：

我们要在 [页面路径] 增加一个信息区块。
约束：不新增依赖；改动最小；保持现有风格。

请先：
1) 告诉我你要读哪些文件（列路径）
2) 给出 3 步计划（每步包含验证命令）
3) 只执行第 1 步并停下来

你需要做的事（人类必须做的）：

  • 看 diff：是否只改了你允许的文件？
  • 跑验证：至少跑一次 lint/typecheck/build
  • 复盘：这次哪些信息一开始没给导致返工？写进规则或模板

常用提示词模板（收藏级）​

1) “先计划再改动”（避免一上来就写代码）​

先给计划，不要直接写代码。

输出格式：
- 你将读取的文件列表
- 3-5 步计划（每步一句 + 验证命令）
- 风险点（最多 3 条）

2) “最小 diff + 可回滚”​

请给最小 diff 的方案。
约束：一次只改一个文件（如果必须多文件，先说明原因）。
最后给回滚方式（撤销哪些改动即可回到原状态）。

3) “写 PR 说明”​

基于这次改动，写一份 PR 描述：
- What changed
- Why
- How tested（命令）
- Risks/mitigations
要求：简洁、可复制到 GitHub。

Cursor 是什么？适合谁？​

Cursor 是 AI 优先的代码编辑器（整体体验接近 VS Code）。你仍然会使用标签页、终端、Git、扩展插件和普通编辑。区别在于：Cursor 把 AI 深度集成到“真实工程工作”中，而不只是补全几行代码。

Cursor 特别擅长：

  • 多文件协同编辑：一个需求同时改 UI + API + 测试。
  • 重构与迁移：一致性改名、文件移动、API 升级。
  • 快速理解仓库：让 AI 帮你定位入口、调用链、边界。

Cursor 更适合：

  • 你的仓库已经不是“几个文件的小脚本”。
  • 你重视可审查、可验证、可回滚的改动。
  • 你希望 AI 能理解项目上下文，而不仅仅是补全。

Cursor 不太适合：

  • 你只需要“打字更快”（Copilot/Codeium 可能更够用）。
  • 你的公司设备对新 IDE 有严格限制。

如何安装 Cursor 并正确完成第一次配置？​

第一步：安装与登录​

  • 下载并安装 Cursor（macOS/Windows/Linux）。
  • 登录账号（套餐、设置与模型能力通常与账号绑定）。

Cursor 大概怎么选套餐？​

Cursor 的套餐细节会随时间变化，但决策逻辑非常稳定：

  • 先用免费/试用，确认它真的能让你写得更快、更稳。
  • 当你能量化节省时间（少 debug、更快重构、更少上下文切换）再升级。

一个简单决策规则：

  1. 偶尔写代码：先用免费/试用。
  2. 每天写代码且经常跨文件改动：升级往往更划算。
  3. 需要团队管理/统一计费：考虑团队/企业方案。

提示：不要为了“答案更像样”买套餐；先把工作流跑顺，再为吞吐量付费。

第二步：务必打开仓库根目录（不要只打开子目录）​

很多“Cursor 不懂我项目”的问题，本质是上下文不完整。

建议：

  • 打开仓库根目录。
  • 等索引/搜索完成。

避免：

  • 只打开 apps/web/ 但真实根目录在上一级。
  • 打开 dist/、build/ 等构建产物目录。

第三步：先定义你的“完成标准”（验证闭环）​

在让 AI 写任何“有意义的改动”之前，先决定哪些命令代表“这次改动可交付”。常见 JS/TS 仓库的最低标准是：

  • pnpm lint
  • pnpm typecheck
  • pnpm build

没有这些也没关系，用项目已有的：

  • pnpm test（单元测试）
  • npm run build / npm run test（以仓库为准）

第四步：把项目规范写进 Cursor Rules​

Cursor Rules（常见文件名 .cursorrules）相当于给 AI 一本“项目手册”。如果不写，你会在每次对话里反复强调同样的规则。

最小但高收益的规则清单：

  • 语言与风格偏好（例如“优先 TypeScript”）。
  • 目录结构（例如 apps/、packages/）。
  • 文件/导出命名规范。
  • 测试约定（测试放哪、怎么命名）。
  • 禁止项（不加依赖、不破坏 API、不输出 secrets）。

示例 .cursorrules：

- 优先 TypeScript。
- diff 要小且可审查。
- 遵循现有目录结构（apps/*, packages/*）。
- 行为变更必须补测试。
- 未明确要求不要新增依赖。
- 永远不要输出或提交任何密钥。

第五步：固定一个“安全默认提示词”​

AI 很容易在信息不足时开始猜。给它一个默认约束可以显著提升稳定性。

你在改一个生产仓库。
1) 先给出简短计划。
2) 列出你会读/改的具体文件。
3) 用最小可行 diff 完成需求。
4) 告诉我如何验证（命令 + 预期结果）。

Chat vs Composer/Agent：我应该用哪个？​

Cursor 通常有多种交互模式。选对模式，比“换模型”更重要。

什么时候用 Chat？​

当你需要理解、诊断、比较方案时，用 Chat：

  • “解释这个模块的职责与边界。”
  • “根据这段报错，列出 3 个最可能原因，并告诉我如何验证。”
  • “方案 A 和 B 在这个仓库的取舍是什么？”

Chat 特别适合：

  • 阅读陌生代码。
  • Debug（堆栈、日志、复现步骤）。
  • 在改代码前先要一个计划。

什么时候用 Composer/Agent 做改动？​

当任务本质是“要改代码”，尤其是跨文件改动时，用 Composer/Agent：

  • “新增一个配置项并贯穿多个模块。”
  • “把 X 重构为 Y，保持行为不变。”
  • “把 API v1 迁移到 v2。”

为了安全，务必提供：

  • 验收标准（acceptance criteria）。
  • 约束（不加依赖、保持兼容、性能要求等）。
  • 验证命令。

示例：

目标：新增 /healthz 路由，返回 {status:"ok"}。
约束：保持现有路由风格；不新增依赖。
验证：pnpm lint、pnpm typecheck、pnpm test。

如何让 Cursor “真正理解项目”（上下文管理）？​

Cursor 最强的能力来自“拿到正确上下文”。注意：不是“上下文越多越好”，而是“刚好够解决问题”。

上下文清单（建议直接粘到提示词里）​

  • 目标（你要达成什么）
  • 预期行为 vs 实际行为
  • 复现步骤
  • 错误/日志（原样粘贴）
  • 环境（Node 版本、框架、OS）
  • 约束（不加依赖、兼容性、性能）
  • 验证方式（命令）

一个高信噪比的 Debug 提示词​

Bug：点击“保存”没有反应。
预期：调用 POST /api/save 并显示 toast。
实际：没有网络请求。
日志：<粘贴 console + server 日志>
相关文件：src/components/SaveButton.tsx、src/api/save.ts
目标：找根因，给最小修复 + 回归测试计划。

如果 AI 开始“拍脑袋”​

立刻让它回到“证据优先”：

在提出修复方案之前，请先列出：
- 你确定的事实
- 你还需要确认的点
- 你要读哪些文件/跑哪些命令来确认
信息不足就问我，不要猜。

Cursor Rules：怎么写才真正有用？​

Cursor Rules 的价值取决于“可执行”。

建议写入的内容​

  1. 风格规则：缩进、引号、是否依赖格式化工具。
  2. 架构规则：路由/服务/组件应该放在哪。
  3. 测试规则：测试目录与命名约定。
  4. 安全规则：不要泄露 secrets、不要做大范围无关重构。

为什么规则不生效？怎么排查？​

  • 最重要的 5 条放最前面。
  • 避免抽象表述（例如“写干净代码”）。
  • 给出可对照的例子（命名、目录）。
  • 在提示词里明确：“请遵循 Cursor Rules”。

Cursor 的日常工作流怎么跑得稳？​

一个工程化的闭环：

  1. 澄清：验收标准 + 约束。
  2. 计划：让 Cursor 给 5-10 步计划。
  3. 执行：一次只做一步。
  4. 验证：跑 lint/typecheck/tests/build。
  5. 审查：看 diff、查边界条件、查安全风险。

工作流 A：拿堆栈修 Bug​

  1. 粘贴堆栈与复现。
  2. 让 AI 给 3 个假设 + 如何验证。
  3. 跑验证步骤。
  4. 做最小修复。
  5. 补回归测试。

工作流 B：实现小功能​

  1. 先要计划与影响文件列表。
  2. 先把接口与类型定好。
  3. 再实现 UI 行为。
  4. 补测试。
  5. 自动化 + 手工双验证。

工作流 C：安全重构（跨文件）​

重构最容易翻车的是“一次改太多”。建议拆分：

  1. 机械性改动（改名/移动/类型）
  2. typecheck/tests
  3. 再做行为层优化
  4. 再跑一遍 typecheck/tests

常用提示词模板（可直接复制）​

模板：让改动可审查​

任务：<描述>
约束：
- 不新增依赖
- diff 要小
- 不改 public API
验证：
- pnpm lint
- pnpm typecheck
- pnpm test
输出：
- 先给计划
- 只实现第 1 步，然后停下来等我审查

模板：只做“行为不变”的重构​

重构目标：提升可读性/性能，但保持行为不变。
非目标：不要改 API 形状。
必须：测试全部通过。
输出：逐条解释每个改动为什么必要，并尽量最小 diff。

模板：先写失败测试​

先为这个 bug 写一个会失败的测试。
然后再修复。
最后解释：这个测试为什么能防止回归。

如何避免 AI 生成的隐性 bug？​

最有效的“防幻觉”策略：

  • 要求列出假设。
  • 要求给出验证命令。
  • 要求最小 diff。
  • 行为变更必须补测试。
写代码前：
- 列出假设
- 列出要读的文件
- 列出要改的文件
- 列出验证步骤
如果信息不足请问我，不要猜。

常见问题与处理方式​

“生成的代码编译不过”​

  • 强制闭环：让它以 pnpm typecheck 为目标迭代到通过。
  • 要求贴近现有模式：“参考相邻文件的写法”。

“一次改太多”​

  • 要求拆步骤，每步停下来。
  • 强调“最小 diff”。

“漏了边界条件”​

  • 要求列出边界条件（空输入、null、超大 payload、错误响应等）。
  • 把边界条件转成测试清单。

“总想加新依赖”​

  • 把“禁止新增依赖”写进 Cursor Rules。
  • 在提示词里重复强调。

进阶：准备好后再用的高级工作流​

成本与模型选择：把“贵模型”用在刀刃上​

Cursor 的体验经常取决于“你把什么任务交给它”。一个更稳、更省的分工方式是：

  • 便宜/快的模型：做机械性编辑（改名、搬文件、补注释、改文案、整理 import）。
  • 更强的模型：做架构推理（找入口、定位调用链、设计改动方案、分解任务与风险）。

实践建议：

  1. 先让它输出“读哪些文件 + 计划 + 风险”，这一步最值钱。
  2. 真正写代码时，把任务拆成可验证的小步，很多小步不需要“最强模型”。
  3. 你越能把验收标准写清楚，越不需要靠更强模型“猜对你的意思”。

团队落地：让 Cursor 成为“可复制”的工作方式​

Cursor 在团队里最常见的失败模式不是“不会写代码”，而是：

  • 每个人提示词不一样，产出质量不稳定
  • AI 改动没人跑验证，导致合并后才爆雷
  • 大改动没人拆步骤，review 压力巨大

一套可执行的团队落地做法：

  1. 统一规则：把必须遵守的约束写进 .cursorrules（不要只写口号）。
  2. 统一模板：在仓库里放一个 PROMPTS.md，或在文档里列出“计划/重构/修 bug”模板。
  3. 统一验证门槛：在提示词里固定要求输出“验证命令 + 预期结果”，并在 PR 中体现。
  4. 统一拆分原则：超过 5 个文件的改动，默认拆成多 PR（除非是纯机械改名）。

如果你在 monorepo（例如有 apps/、packages/、content/）里工作，可以把这些“踩坑提醒”写进规则：

- 这是一个 monorepo；修改前先确认目标 app/package。
- docs 内容在 `content/`（可能是 submodule）；修改后务必检查 submodule 状态。
- 不要改构建产物目录（dist/build）。
- 每次改动都要给出验证命令：pnpm lint / pnpm typecheck / pnpm build（以仓库为准）。

场景食谱：5 个高频任务怎么提问（可直接复制）​

1) 修构建失败（最小修复）​

pnpm build 失败，报错如下：<粘贴关键错误>
目标：找根因并做最小修复，避免无关重构。
请先：
1) 列出要读的文件/配置
2) 给 3-5 步计划（每步包含验证命令）
3) 只执行第 1 步并停下来

2) 重构但保持行为不变（可审查）​

重构目标：把 <模块/函数> 拆分成更清晰的结构，但保持行为不变。
约束：不改 public API；不新增依赖；diff 尽量小。
验证：pnpm typecheck + pnpm test（或项目等价命令）。
输出：先列“哪些改动是机械的/哪些可能影响行为”，再开始做机械部分。

3) 新增文档/教程页面（结构化 + SEO/GEO）​

我要新增一篇文档页面：<主题>。
目标：结构清晰（TL;DR/步骤/FAQ），并加上页面内的相关链接（路线图/课程/FAQ）。
约束：保持现有写作风格；不要改变侧边栏结构（除非我要求）。
请先给页面大纲（含标题、要点、FAQ 问题列表），再开始写正文。

4) 让 AI 先做“代码考古”（理解仓库）​

我不确定入口在哪里。
目标：理解 <功能> 的调用链（从入口到输出）。
请：
1) 指出入口文件/路由/命令
2) 画出 5-8 个关键文件的调用链（用路径）
3) 给出“我为了做 <任务> 最该先读的 3 个文件”

5) 写 PR 说明 + 回滚计划​

基于本次 diff，请写：
1) PR 描述（What/Why/How tested）
2) 风险点（最多 3 条）
3) 回滚计划（撤销哪些改动即可）
要求：简洁可复制。

30 分钟上手挑战：从 0 到一个可合并的小 PR​

如果你想真正把 Cursor 用起来，不要从“写一大堆提示词”开始，直接做一个可验证的小改动：

  1. 选一个小任务（改文案、补一段文档、修一个小 bug），范围限定在 1-2 个文件
  2. 让 Cursor 先输出：文件清单 + 3 步计划 + 验证命令
  3. 只执行第 1 步，停下来让你看 diff
  4. 跑验证（至少跑一次 typecheck/lint/build 中你项目最便宜的那一个）
  5. 让 Cursor 帮你写 PR 描述（What/Why/How tested）

可复制提示词：

我们做一个 30 分钟小任务练习。
任务：<一句话描述>
范围：只改 <文件 A>（如必须再加文件 B，请先解释原因）
约束：不新增依赖；diff 尽量小；保持现有风格
请：
1) 列出你要读的文件
2) 给 3 步计划（每步包含验证命令）
3) 只执行第 1 步并停下来等我审查

如何快速上手一个陌生仓库？​

  1. 让 AI 找入口（路由、启动文件、配置）。
  2. 要一个依赖/调用链地图。
  3. 问清楚边界（API 层/UI 层/共享库）。
  4. 让它给你“为当前任务最该先读的 1 个文件”。
我刚接触这个仓库。
目标：我要改 <功能>。
请：
1) 标出入口与关键目录。
2) 解释一次请求/流程从入口到输出。
3) 列出最可能需要改的 3 个文件。

如何做大重构而不炸？​

两阶段：

  • 第 1 阶段只做机械改动（不改行为），每步都验证。
  • 第 2 阶段再做行为层改进。
这个重构分两阶段。
阶段 1：只做机械改动（不改行为），做完停下来我审查。
每一步后都跑：pnpm typecheck + pnpm test。

如何让 Cursor 帮你产出“PR 级别”的内容？​

除了代码，还可以让它帮你写：

  • PR 描述（What/Why/How/How tested）。
  • 风险与回滚计划。
  • 发布/灰度步骤。
根据本次 diff，写一段 PR 描述：
- What changed（要点）
- Why
- How tested（命令）
- Risk/mitigation
要求简洁。

FAQ​

Cursor 比 GitHub Copilot 强在哪里？​

Cursor 通常更强在 项目级改动（多文件编辑、重构）。Copilot 更强在 行内补全 与“打字速度”。很多人会组合使用：Copilot 负责快，Cursor 负责大改动。

一定要买 Pro 才有价值吗？​

不一定。先用免费/试用把工作流跑顺；当你能清晰感受到节省的时间再升级。

Cursor 总是改太多怎么办？​

要求分步骤，并且每一步停下来让你审查；强调“最小 diff”。

私密代码/密钥怎么处理？​

不要粘贴密钥。用 REDACTED 替代；必要时提供最小复现或描述数据结构。

大仓库怎么提高准确率？​

给更窄的范围：明确文件列表/目录范围/验收标准；把关键入口文件直接指给它看。

最快的学习方式是什么？​

选一个固定流程（修 bug 或小功能），每周重复几次，强化“计划 → 改动 → 验证”的闭环。

相关学习路径​

下一步​