Cursor 配置与最佳实践

Cursor 是基于 VS Code 深度定制的 AI 代码编辑器，将大语言模型直接集成到编辑器核心，提供代码补全、多文件编辑、对话式编程等能力。本文介绍如何配置 Cursor 以获得最佳开发体验。

.cursorrules 文件配置

.cursorrules 是 Cursor 的项目级 AI 规则配置文件，放在项目根目录，所有 AI 功能都会遵守其中定义的规则。

注意：较新版本的 Cursor 已迁移到 .cursor/rules/ 目录结构，但 .cursorrules 仍向后兼容。

基础结构

plaintext

# .cursorrules

## 项目信息
[简短描述项目的技术栈、目的和架构]

## 代码规范
[具体的代码风格要求]

## 命名约定
[变量、函数、文件的命名规则]

## 架构约束
[目录结构、模块边界、禁止事项]

## 测试要求
[测试框架、覆盖率要求、测试规范]

完整示例：React TypeScript 项目

plaintext

# .cursorrules

## 技术栈
- React 18 + TypeScript 5
- Vite 作为构建工具
- Tailwind CSS 用于样式
- React Query 用于服务端状态管理
- Zustand 用于客户端状态

## 代码规范
- 所有组件使用函数式组件 + Hooks
- Props 必须定义 TypeScript interface，不使用 type alias
- 禁止使用 any 类型，必要时使用 unknown
- 异步操作统一使用 async/await，不使用 .then() 链
- 导入顺序：React → 第三方库 → 内部模块 → 样式

## 文件结构
src/
  components/       # 通用 UI 组件
  features/         # 业务功能模块（按功能划分）
    [feature-name]/
      components/   # 该功能的局部组件
      hooks/        # 该功能的自定义 Hooks
      api.ts        # API 调用
      types.ts      # 类型定义
  hooks/            # 全局共享 Hooks
  stores/           # Zustand stores
  utils/            # 纯函数工具

## 组件规范
- 每个文件只导出一个主组件
- 组件文件名与组件名一致，使用 PascalCase
- 自定义 Hook 以 use 开头，文件名同步
- 避免组件超过 150 行，超出则拆分

## 样式规范
- 优先使用 Tailwind 原子类
- 复杂样式使用 clsx/cn 工具函数组合
- 不使用内联 style，除非动态计算的值

## 禁止事项
- 不要在组件中直接调用 fetch，必须通过 React Query
- 不要修改 src/generated/ 目录（自动生成）
- 不要使用 class 组件

新版 `.cursor/rules/` 结构

Cursor 1.0+ 支持按规则分文件管理，更易维护：

plaintext

.cursor/
  rules/
    general.mdc      # 通用规范
    react.mdc        # React 相关规范
    testing.mdc      # 测试规范
    api.mdc          # API 调用规范

每个 .mdc 文件支持设置触发条件：

yaml

---
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

# React 组件规范
...规则内容...

Composer 模式：多文件编辑

Composer（快捷键 Ctrl+I / Cmd+I）是 Cursor 最强大的功能，能够同时理解和修改多个文件。

启动 Composer

Ctrl+I (Windows/Linux)
Cmd+I  (macOS)

或通过菜单：View → Composer

Composer 的核心能力

1. 跨文件重构

在 Composer 中输入：
> 将 UserProfile 组件从类组件重构为函数式组件，
> 同时更新所有引用该组件的测试文件

2. 功能生成

> 基于 src/types/api.ts 中的 Product 类型，
> 生成完整的 CRUD 操作：
> - API 函数（src/features/products/api.ts）
> - React Query hooks（src/features/products/hooks.ts）
> - 列表页面组件（src/features/products/ProductList.tsx）
> - 详情页面组件（src/features/products/ProductDetail.tsx）

3. 添加上下文

在 Composer 中使用 @ 符号引用文件、代码或文档：

引用方式	示例	说明
`@文件名`	`@api.ts`	引用特定文件
`@文件夹`	`@src/utils`	引用整个目录
`@代码符号`	`@UserService`	引用特定函数/类
`@Web`	`@Web react hooks`	搜索网络文档
`@Docs`	`@Docs`	引用已索引的文档

Composer 最佳实践

具体说明文件范围：明确告诉 Composer 应该创建/修改哪些文件
分步确认：大型修改先审查 diff，再接受
使用 Checkpoint：Composer 会自动创建检查点，出错可回滚
善用 Reject All：不满意时一键撤销所有更改

Tab 补全优化

Cursor 的 Tab 补全（称为 "Cursor Tab"）比普通代码补全更智能，能预测多行更改。

配置补全行为

json

// .vscode/settings.json（或 Cursor 设置）
{
  "cursor.cpp.disabledLanguages": ["plaintext", "markdown"],
  "cursor.tab.enabled": true,
  "cursor.tab.multilineEnabled": true
}

提升补全质量的技巧

1. 写好函数签名和注释

typescript

// 清晰的函数签名帮助 Cursor 预测实现
/**
 * 计算购物车中所有商品的总价，应用优惠券折扣
 * @param items 购物车商品列表
 * @param coupon 优惠券（可选），包含折扣率
 * @returns 折扣后的总价（保留两位小数）
 */
function calculateCartTotal(items: CartItem[], coupon?: Coupon): number {
  // 按 Tab 让 Cursor 完成实现
}

2. 利用已有代码模式

当项目中有类似实现时，Cursor Tab 会参考这些模式生成一致的代码。

3. 部分接受

不必接受全部建议：

Tab：接受完整建议
Ctrl+→：逐词接受
Esc：拒绝建议

Chat 模式最佳实践

Chat（Ctrl+L / Cmd+L）适合问答、代码解释和局部修改。

有效提问模式

# 解释代码
> 解释 @calculateTax 函数的逻辑，特别是边界情况处理

# 定向修改
> 修改 @UserForm.tsx，在提交前添加表单验证，
> 使用 react-hook-form 的 resolver，错误信息显示在字段下方

# 调试分析
> 为什么 @useCartStore 中的 removeItem 函数在商品数量为 1 时
> 没有正确从数组中删除？

Chat 的上下文管理

使用 + 按钮开启新对话，避免上下文污染
长对话中使用"总结之前的讨论"重置焦点
引用代码时选中后按 Ctrl+L 自动附加到对话

项目级规则进阶配置

针对不同文件类型的规则

plaintext

# .cursorrules

## 测试文件规范（仅对 *.test.ts 生效）
当编写测试文件时：
- 使用 describe/it 结构，不使用 test()
- 每个 describe 块只测试一个函数
- Mock 外部依赖，不发真实网络请求
- 测试描述用中文，方便阅读测试报告

## API 路由规范（仅对 src/routes/**）
- 所有路由函数必须有错误处理 try/catch
- 统一使用 sendSuccess() 和 sendError() 响应工具函数
- 路由不包含业务逻辑，只做参数验证和调用 Service

与团队共享规则

将 .cursorrules 纳入版本控制，确保团队一致性：

bash

# 添加到 Git
git add .cursorrules
git commit -m "chore: add Cursor AI rules for project conventions"

# 个人不想提交的规则放在
# .cursorignore 或 Git 忽略的独立文件中

与现有工作流集成

集成 ESLint 和 Prettier

在 .cursorrules 中明确引用项目的 linting 配置：

plaintext

## 代码格式
- 所有代码必须通过 ESLint（配置见 .eslintrc.js）
- 格式化遵循 Prettier 配置（见 .prettierrc）
- 生成代码后，假设会自动运行格式化，不要手动添加多余空格

集成 Git 工作流

plaintext

## Git 规范
- commit message 格式：<type>(<scope>): <subject>
- type: feat | fix | chore | docs | refactor | test
- 示例：feat(auth): add password reset functionality

与 CI/CD 对齐

plaintext

## CI 检查
项目 CI 会运行以下检查，生成的代码必须能通过：
1. TypeScript 编译：tsc --noEmit
2. ESLint：eslint src/
3. 单元测试：jest --coverage（覆盖率不低于 80%）
4. E2E 测试：playwright test

常见问题与解决

问题	原因	解决方案
补全质量下降	上下文过长或无关	开新 Chat，精简 `.cursorrules`
Composer 修改了不该改的文件	描述不够精确	明确指定"只修改 X 文件"
AI 忽略了 `.cursorrules`	文件过长，规则被截断	精简至 500 字以内核心规则
Tab 补全频繁打断思路	补全延迟设置过低	在设置中调整触发延迟

快捷键速查

功能	Windows/Linux	macOS
打开 Chat	`Ctrl+L`	`Cmd+L`
打开 Composer	`Ctrl+I`	`Cmd+I`
接受 Tab 补全	`Tab`	`Tab`
拒绝补全	`Esc`	`Esc`
内联编辑	`Ctrl+K`	`Cmd+K`
新建 Chat	`Ctrl+N`（在 Chat 中）	`Cmd+N`
引用文件	`@` + 文件名	`@` + 文件名

Cursor 配置与最佳实践 ​

.cursorrules 文件配置 ​

基础结构 ​

完整示例：React TypeScript 项目 ​

新版 .cursor/rules/ 结构 ​

Composer 模式：多文件编辑 ​

启动 Composer ​

Composer 的核心能力 ​

Composer 最佳实践 ​

Tab 补全优化 ​

配置补全行为 ​

提升补全质量的技巧 ​

Chat 模式最佳实践 ​

有效提问模式 ​

Chat 的上下文管理 ​

项目级规则进阶配置 ​

针对不同文件类型的规则 ​

与团队共享规则 ​

与现有工作流集成 ​

集成 ESLint 和 Prettier ​

集成 Git 工作流 ​

与 CI/CD 对齐 ​

常见问题与解决 ​

快捷键速查 ​

Cursor 配置与最佳实践

.cursorrules 文件配置

基础结构

完整示例：React TypeScript 项目

新版 `.cursor/rules/` 结构

Composer 模式：多文件编辑

启动 Composer

Composer 的核心能力

Composer 最佳实践

Tab 补全优化

配置补全行为

提升补全质量的技巧

Chat 模式最佳实践

有效提问模式

Chat 的上下文管理

项目级规则进阶配置

针对不同文件类型的规则

与团队共享规则

与现有工作流集成

集成 ESLint 和 Prettier

集成 Git 工作流

与 CI/CD 对齐

常见问题与解决

快捷键速查