【Cursor 进阶指南】老规则系统说拜拜!手把手带你玩转 ...

在 Vibe 编程的浪潮中，Cursor 的规则系统升级是开发者体验的一次重要飞跃。从 .cursorrules 到 .cursor/rules，这一变化不仅提升了代码质量的一致性，还极大地增强了规则管理的灵活性和可维护性。本文将深入解析 Cursor 新规则系统的特性，并提供从 0 到 1 的迁移指南与实战技巧，帮助你打造更加高效的开发流程。

一、告别旧时代 - 为什么要迁移？🤔

在 Vibe 编程生态中，代码规范和自动化工具的重要性日益凸显。Cursor 的旧规则系统 .cursorrules 虽然为开发者提供了基础的规则配置功能，却存在诸多限制，影响了团队协作和代码质量的统一。

1.1 单文件限制 📄

旧规则系统将所有规则集中在一个文件中，导致：

• 规则难以维护：文件臃肿，结构混乱，难以快速找到相关规则。
• 无法针对不同模块设置规则：同一套规则应用于整个项目，缺乏灵活性。
• 团队协作困难：多人同时修改同一文件时容易产生冲突。

1.2 规则冲突 ⚔️

旧规则系统缺乏优先级设置和匹配控制，导致：

• 全局规则与项目规则冲突：规则覆盖范围不可控，容易引发误判。
• 无法设置规则优先级：容易出现规则间的相互覆盖，影响代码风格的一致性。
• 缺乏全局管理能力：开发者无法直观地了解规则的应用范围和行为。

1.3 功能单一 🔨

旧规则系统功能较为单一，主要体现在：

• 不支持规则继承和复用：规则文件之间无法共享配置，导致重复劳动。
• 缺乏文件匹配能力：无法根据文件类型或路径灵活选择规则。
• 规则描述能力有限：缺乏对规则的组织和文档说明，理解成本高。

二、迁移实战 - 从 0 到 1 的升级指南 🛠️

2.1 创建规则目录

升级 Cursor 规则系统的第一步是创建规则目录：

mkdir -p .cursor/rules

2.2 规则文件结构

新的 .cursor/rules 系统采用 .mdc 文件格式，每份规则文件包含两部分：

• YAML 头部配置：定义规则名称、描述、匹配范围、优先级等信息。
• Markdown 规则内容：包含规则的具体描述和最佳实践。

一个完整的规则文件示例如下：

name: typescript-rules
description: TypeScript coding standards and best practices
globs:
    - 'src/**/*.ts'
    - 'src/**/*.tsx'
    - '!src/**/*.test.ts'
priority: 1

# TypeScript Coding Standards

## 基础规范

- 使用 2 空格缩进
- 优先使用 const 声明变量
- 显式声明函数返回类型

## 最佳实践

- 避免 any 类型
- 合理使用泛型
- 接口优于类型别名

## 参考文档

Read more from @common-rules.mdc

2.3 规则分类示例

为了更好地组织和管理规则，建议按照项目模块来划分规则文件，例如：

.cursor/rules/
├── common/
│   ├── general.mdc     # 通用规则
│   └── git.mdc         # Git 规范
├── frontend/
│   ├── java script.mdc  # JS 规则
│   ├── typescript.mdc  # TS 规则
│   └── react.mdc       # React 规则
├── backend/
│   ├── node.mdc       # Node.js 规则
│   └── database.mdc   # 数据库规则
└── style/
    ├── css.mdc        # CSS 规则
    └── less.mdc       # LESS 规则

这种方式不仅便于管理，还提升了团队协作的效率。

2.4 Glob 模式详解

新系统支持强大的 globs 匹配模式，使你可以更精细地控制规则的应用范围：

globs:
    # 匹配所有 .ts 文件
    - '**/*.ts'

    # 排除测试文件
    - '!**/*.test.ts'

    # 排除构建目录
    - '!**/dist/**'
    - '!**/build/**'

    # 匹配特定目录
    - 'src/components/**/*.tsx'

常用的 glob 语法如下：

• *：匹配任意文件名
• **：匹配任意目录深度
• !：排除匹配
• {}：组合匹配（例如：{a,b,c}.mdc 可以匹配 a.mdc、b.mdc、c.mdc）

通过这些模式，你可以实现更精准的规则匹配，避免误伤非目标文件。

三、进阶技巧 - 玩转规则系统 🎯

3.1 规则继承与复用

使用 @file 语法可以引用其他规则文件，实现规则的继承和复用：

# React 组件规范

继承通用前端规范 @frontend/common.mdc

## 特殊规则

- 使用函数组件
- 采用 Hooks 开发

这种方式可以避免重复编写规则，同时保持代码的整洁。

3.2 个人规则配置

如果你希望设置个性化的规则，可以创建个人专属的规则目录：

mkdir -p .cursor/rules/personal

同时，建议将该目录添加到 .gitignore 中，避免多人协作时产生冲突。

3.3 规则优先级

通过 priority 字段可以控制规则的优先级：

name: override-rules
description: Override default rules
priority: 100 # 高优先级规则

规则优先级说明如下：

• 数字越大优先级越高：优先级为 100 的规则会覆盖优先级为 1 的规则。
• 默认优先级为 0：未指定优先级的规则具有默认优先级。
• 相同优先级按文件名排序：如果两个规则的优先级相同，文件名较短的会优先应用。

3.4 条件规则

新系统支持根据环境变量设置规则，例如：

name: dev-rules
description: Development environment rules
when: ${NODE_ENV} === 'development'

这种方式可以实现不同环境下的不同规则，提高灵活性。

3.5 规则模板

为了便于复用，可以创建规则模板：

name: rule-template
description: Template for new rules

# ${name} 规范

## 基础规则

${rules}

## 最佳实践

${practices}

通过变量替换，可以在不同规则文件中重复使用模板内容。

四、实战案例 - 规则系统应用场景 💡

4.1 多人协作项目

在大型团队中，规则的统一和管理至关重要。推荐的规则结构如下：

.cursor/rules/
├── team/              # 团队通用规则
├── projects/          # 项目特定规则
└── members/           # 成员个性化规则

• team/：存放团队层面的通用规则，适用于所有成员。
• projects/：针对不同项目设置规则，提升代码风格的统一性。
• members/：每位成员可在此创建个性化规则，不影响团队整体规则。

4.2 Monorepo 项目

对于 Monorepo 项目，可以采用以下方式设置规则：

name: package-rules
description: Rules for specific package
globs: ['packages/*/src/**/*.ts']

这种方式可以确保每个子包遵循统一的代码规范，避免因不同子项目导致的风格混乱。

4.3 微前端项目

在微前端架构中，每个子应用可能有不同的代码规范。可以为不同子应用设置独立的规则文件：

.cursor/rules/
├── main/             # 主应用规则
└── sub-apps/         # 子应用规则
    ├── app1.mdc
    └── app2.mdc

每个子应用规则文件可以包含其特有的规范，例如：

name: app1-rules
description: App1 specific coding standards
globs:
    - 'src/app1/**/*.tsx'
    - 'src/app1/**/*.ts'
priority: 3

五、注意事项 ⚠️

5.1 迁移时间

.cursorrules 将在未来版本中被废弃，建议尽早完成迁移。在迁移过程中，可以保留旧规则文件作为备份，避免误删除。

5.2 规则冲突

• 注意 glob 匹配范围：确保规则匹配的路径准确，避免覆盖非目标文件。
• 合理设置优先级：避免规则之间的冲突，优先级设置要清晰明了。
• 避免循环引用：规则文件之间引用要保持单向，防止无限循环。

5.3 性能考虑

• 规则文件不宜过大：过大文件会影响加载性能，建议拆分规则文件。
• 避免过于复杂的 glob 模式：复杂的匹配模式可能影响规则解析效率。
• 适当使用规则缓存：合理使用缓存可以提升规则的加载速度。

5.4 团队协作

• 统一规则命名规范：规则文件的命名要统一，便于查找和管理。
• 做好规则文档：为每份规则文件编写清晰的说明，便于团队成员理解。
• 及时同步规则变更：规则变更后要及时通知团队，确保一致的使用体验。

六、最佳实践配置示例 📚

6.1 React 项目配置示例

name: react-rules
description: React project best practices and coding standards
globs:
    - 'src/**/*.tsx'
    - 'src/**/*.jsx'
    - 'src/**/*.ts'
priority: 2

# React 项目规范

## 组件规范

### 基础规则

- 使用函数组件 + Hooks 模式
- 组件文件使用 .tsx 扩展名
- 组件名使用 PascalCase
- 文件名与组件名保持一致

### 目录结构

src/
├── components/        # 通用组件
├── pages/            # 页面组件
├── hooks/            # 自定义 hooks
├── utils/            # 工具函数
├── services/         # API 服务
├── types/            # TypeScript 类型
└── styles/           # 样式文件

### Hooks 使用规范

- 自定义 Hook 以 `use` 开头
- 避免在循环/条件语句中使用 Hooks
- 合理使用 useMemo 和 useCallback
- 使用 useContext 管理全局状态

### 性能优化

- 合理拆分组件
- 使用 React.memo 避免不必要渲染
- 使用 React.lazy 实现代码分割
- 图片使用 next/image 优化

### TypeScript 集成

- 为 Props 定义接口
- 使用 FC 类型声明组件
- 避免使用 any
- 合理使用泛型

6.2 Vue 项目配置示例

name: vue-rules
description: Vue.js project best practices and coding standards
globs:
  - "src/**/*.vue"
  - "src/**/*.ts"
priority: 2

# Vue 项目规范

## 组件规范

### 基础规则

- 使用 Composition API
- 组件名使用 PascalCase
- Props 定义使用 defineProps
- 事件使用 defineEmits

### 目录结构

src/
├── components/        # 通用组件
├── views/            # 页面视图
├── composables/      # 组合式函数
├── utils/            # 工具函数
├── api/              # API 接口
├── types/            # TypeScript 类型
└── assets/           # 静态资源

### 组合式函数规范

- 以 `use` 开头命名
- 一个函数只做一件事
- 返回响应式数据
- 注意依赖收集

### 性能优化

- 合理使用 computed
- v-show vs v-if
- 使用 defineAsyncComponent
- keep-alive 缓存

### TypeScript 集成

- 使用 defineComponent
- Props 类型声明
- 组件实例类型
- 响应式类型

6.3 样式文件配置示例

name: style-rules
description: CSS/LESS/SCSS styling best practices
globs:
    - 'src/**/*.css'
    - 'src/**/*.less'
    - 'src/**/*.scss'
    - 'src/**/*.module.*'
priority: 1

# 样式规范

## 命名规范

### BEM 命名

- Block: 独立实体
- Element: 使用双下划线 \_\_
- Modifier: 使用双横线 --

.block {}
.block\_\_element {}
.block--modifier {}

### CSS Modules

- 文件名使用 .module.css
- 类名使用小驼峰
- 避免全局样式
- 合理使用组合

## 目录结构

styles/
├── global/ # 全局样式
├── themes/ # 主题文件
├── variables/ # 变量定义
├── mixins/ # 混入
└── components/ # 组件样式

## 响应式设计

- 使用相对单位
- 移动优先原则
- 合理使用媒体查询
- 避免固定宽度

### 断点设置

@screen-xs: 480px;
@screen-sm: 576px;
@screen-md: 768px;
@screen-lg: 992px;
@screen-xl: 1200px;

## 性能优化

- 避免深层嵌套
- 合理使用选择器
- 压缩和合并
- CSS 代码分割

## 主题定制

- 使用 CSS 变量
- 设计 Token 系统
- 暗黑模式支持
- 主题切换方案

## 最佳实践

- 避免 !important
- 模块化样式
- 注释规范
- 代码复用

七、总结 & 展望 🎉

新的 .cursor/rules 系统带来了以下显著优势：

• 更好的规则管理：支持多文件、分类管理，提升可读性和可维护性。
• 更强的扩展能力：支持规则继承、条件匹配、优先级设置，灵活性大幅提升。
• 更棒的使用体验：规则变更后自动生效，无需手动重启，开发效率显著提高。

虽然配置上稍微复杂了一点，但带来的收益是显而易见的。未来，Cursor 有望进一步优化规则系统，引入更智能的规则建议、自动化分析等功能，为开发者提供更加个性化的体验。

关键字列表：Cursor, 规则系统, .cursor/rules, glob 匹配, 优先级设置, React, Vue, TypeScript, 样式规范, 规则继承, 开发效率