Cursor AI IDE：完整功能指南

Cursor 安装与基础配置

安装 Cursor

Cursor 基于 VS Code 构建，如果你已经熟悉 VS Code，迁移成本极低。Cursor 可以直接导入你的 VS Code 插件和设置。

# macOS：使用 Homebrew 安装
brew install --cask cursor

# 或直接从官网下载：https://cursor.sh
# 支持 macOS、Windows、Linux

# 首次启动后，迁移 VS Code 配置
# Cursor 菜单 → Import VS Code Settings

模型选择

Cursor 支持多个底层模型，你可以根据任务特点选择：

Tab 补全：智能代码预测

Cursor Tab 的差异化

Cursor 的 Tab 补全不只是单行续写，它支持多行预测编辑（Predictive Edits）：当你修改一处代码时，Cursor 会预测你接下来可能要做的其他修改，并以灰色显示建议。按 Tab 接受，按 Escape 拒绝。

// 修改函数参数名后，Cursor Tab 会自动预测其他地方的同步修改
function getUserById(userId: number) {  // 你把 userId 改成 id
  const user = db.find(userId)         // Cursor 预测：这里也改成 id
  if (!user) throw new Error(`User ${userId} not found`)  // 这里也改
  return user
}

Composer：多文件 AI 编辑

Composer 是什么？

Composer（Ctrl+I / Cmd+I）是 Cursor 最强大的功能，它允许 AI 同时编辑多个文件，完成需要跨文件协调的任务。这是 Cursor 与普通 AI 代码助手最重要的区分点。

# Composer 使用示例

# 示例 1：添加新功能（会自动修改多个相关文件）
添加用户头像上传功能：
- 在 UserModel 中添加 avatar_url 字段
- 更新 UserSchema 包含 avatar_url
- 在 user_router.py 添加 POST /users/{id}/avatar 端点
- 创建 avatar_service.py 处理文件上传到 S3
- 更新 migration 文件

# 示例 2：重构代码（跨多文件）
将所有数据库查询从同步改为异步，使用 SQLAlchemy 2.0 异步 API

# 示例 3：修复 Bug（可能涉及多个文件）
修复用户登录时的竞争条件：当并发请求时会生成重复的 session token

Normal Mode vs Agent Mode

Chat 对话：精准上下文引用

@ 符号引用系统

Cursor Chat（Ctrl+L）支持强大的 @ 引用系统，让你精确控制 AI 的上下文：

@docs 文档集成详解

# 在 Cursor 设置中添加文档源
Settings → Cursor Settings → Docs → Add new doc

# 添加 FastAPI 文档
Name: FastAPI
URL: https://fastapi.tiangolo.com

# 添加完成后，在 Chat 中使用
@FastAPI 如何在路由中定义响应模型的嵌套结构？

# 常用文档源推荐
- React: https://react.dev
- Next.js: https://nextjs.org/docs
- Tailwind CSS: https://tailwindcss.com/docs
- SQLAlchemy: https://docs.sqlalchemy.org

Rules for AI：项目规则体系

.cursorrules 文件

类似于 GitHub Copilot 的 copilot-instructions.md，Cursor 使用 .cursorrules 文件（放在项目根目录）定义 AI 行为规范。这个文件的内容会作为系统提示注入每次对话：

# .cursorrules 示例（React/TypeScript 项目）

You are an expert TypeScript and React developer.

## Tech Stack
- React 18 with TypeScript strict mode
- Vite as build tool
- TanStack Query v5 for data fetching
- Zustand for global state
- Tailwind CSS for styling
- Vitest + React Testing Library for tests

## Code Style Rules
- Always use functional components with hooks, never class components
- Use named exports, not default exports (except pages)
- Prefer const arrow functions: `const MyComponent = () => {}`
- Use TypeScript interfaces, not types, for object shapes
- All async functions must handle errors with try/catch

## File Organization
- Components: src/components/{ComponentName}/index.tsx
- Hooks: src/hooks/use{HookName}.ts
- Utils: src/utils/{feature}.ts

## Forbidden Patterns
- No any type unless absolutely necessary (explain why in comment)
- No useEffect for data fetching (use TanStack Query)
- No inline styles (use Tailwind classes)
- No console.log in production code (use logger)

Rules for AI（新版界面设置）

Cursor 新版本（0.40+）引入了在设置界面管理规则的方式，支持全局规则和项目规则的分离：

• User Rules：全局规则，对所有项目生效。适合个人偏好（如"回答用中文"）
• Project Rules：通过 .cursor/rules/ 目录下的 .mdc 文件定义，支持按文件类型应用不同规则

# .cursor/rules/python.mdc（只对 .py 文件生效）

---
globs: ["**/*.py"]
---

Use Python 3.12 type hints.
Always use `async def` for I/O bound operations.
Follow PEP 8 naming conventions.

# .cursor/rules/tests.mdc（只对测试文件生效）

---
globs: ["**/test_*.py", "**/*_test.py"]
---

Use pytest with fixtures.
Mock external services with pytest-mock.
Each test should have clear Arrange/Act/Assert sections.

Cursor Agent：自主任务执行

Agent 能力边界

Cursor Agent（在 Composer 中选择 Agent 模式）可以自主执行以下操作：

• 在代码库中搜索相关文件（grep、语义搜索）
• 读取和修改多个文件
• 在终端执行命令（npm install、运行测试等）
• 读取命令输出并根据结果调整策略
• 创建新文件和目录

# Agent 模式的典型任务描述

"为项目添加 GitHub Actions CI/CD 流水线：
1. 在每次 PR 时运行测试
2. 在合并到 main 时自动构建 Docker 镜像并推送到 Docker Hub
3. 包含 lint 检查（ESLint）和类型检查（tsc --noEmit）
4. 缓存 node_modules 提升速度"

# Agent 会自动
# 1. 检查现有的 package.json 了解测试命令
# 2. 检查是否有 Dockerfile
# 3. 创建 .github/workflows/ci.yml
# 4. 创建 .github/workflows/deploy.yml（如果没有 Dockerfile 还会创建）

Cursor 的技术架构深解

@codebase 的向量检索原理

理解 @codebase 功能的原理，才能知道它什么时候有效、什么时候失效：

Composer 多文件编辑的内部机制

Composer 与普通 Chat 的核心区别：Composer 有一个"差异应用（Diff Application）"步骤，而 Chat 只生成文本。

Chat 模式：
  你的消息 → Claude 生成文本 → 你手动复制粘贴

Composer 模式：
  你的消息 + 引用的文件内容
    → Claude 生成 [文件路径] + [修改后的完整文件内容]
    → Cursor 解析生成内容，自动计算 diff
    → 在 IDE 中显示红/绿高亮的 diff
    → 你按 Accept All 或 Review & Accept

为什么 Composer 比 Chat 更适合多文件修改：
  1. 原子性：所有文件修改在你确认前都不会真正写入
  2. 可预览：diff 视图让你精确看到每行的变化
  3. 批量操作：一次请求可以修改 5-10 个文件
  4. 上下文共享：Composer 会话中所有文件共享同一对话上下文

Rules for AI（.cursorrules）的工作原理

.cursorrules 文件中的内容会被注入到每次 Chat/Composer 请求的系统提示词（System Prompt）中。理解这一点很重要：

实际发送给 Claude 的消息结构：

System Prompt:
  [Cursor 内置系统提示词]
  +
  [你的 .cursorrules 内容]

User Message:
  [你的提问]
  +
  [#file 引用的文件内容]
  +
  [@codebase 检索的代码块]

常见问题：Cursor 使用中的坑