【Cursor 进阶指南】老规则系统说拜拜!手把手带你玩转 .cursor/rules 🚀 - 文章 - 开发者社区

作者：陈大鱼头

github：https://github.com/KRISACHAN

邮箱：chenjinwen77@gmail.com

前言

大家好,我是陈大鱼头 🐟

最近在折腾 Cursor 编辑器的时候发现它更新了规则系统,从原来的 .cursorrules 迁移到了 .cursor/rules。这次更新可以说是一次重大升级,不仅解决了很多痛点,还带来了超多实用的新特性!

今天就给大家详细讲讲这次迁移的方方面面,建议收藏慢慢看~

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

在聊新系统之前，我们先来看看老的 .cursorrules 有哪些问题：

1.1 单文件限制 📄

规则堆积在一起，难以维护 😫
无法针对不同模块设置规则
团队协作困难

1.2 规则冲突 ⚔️

全局规则和项目规则容易冲突
无法设置规则优先级
规则覆盖范围不可控

1.3 功能单一 🔨

不支持规则继承和复用
缺乏文件匹配能力
规则描述能力有限

而新的 .cursor/rules 系统则完全解决了这些问题！它支持：

✨ 多文件管理：可以创建多个规则文件，分类管理 ✨ Glob 匹配：精确控制规则应用范围 ✨ 规则继承：支持规则文件之间的引用 ✨ 自动加载：规则变更后自动生效 ✨ 版本控制：更好的团队协作体验

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

2.1 创建规则目录

首先需要在项目根目录创建规则文件夹:

# 创建规则目录
mkdir -p .cursor/rules

# 可选:将旧规则文件移动到新目录
mv .cursorrules .cursor/rules/general.mdc

2.2 规则文件结构

新的规则文件采用 .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/
│   ├── javascript.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 模式详解

新系统支持强大的 glob 匹配模式:

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

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

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

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

常用的 glob 语法:

*: 匹配任意文件名
**: 匹配任意目录深度
!: 排除匹配
{}: 组合匹配

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

3.1 规则继承与复用

使用 @file 语法引用其他规则:

# React 组件规范

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

## 特殊规则

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

3.2 个人规则配置

创建个人专属规则:

# 创建个人规则目录
mkdir -p .cursor/rules/personal

# 添加到 .gitignore
echo ".cursor/rules/personal/" >> .gitignore

3.3 规则优先级

通过 priority 字段控制规则优先级:

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

优先级说明:

数字越大优先级越高
默认优先级为 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/           # 成员个性化规则

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

五、注意事项 ⚠️

迁移时间
- .cursorrules 将在未来版本废弃
- 建议尽快完成迁移工作
- 保留旧规则作为备份
规则冲突
- 注意 glob 匹配范围
- 合理设置优先级
- 避免循环引用
性能考虑
- 规则文件不宜过大
- 避免过于复杂的 glob 模式
- 适当使用规则缓存
团队协作
- 统一规则命名规范
- 做好规则文档
- 及时同步规则变更

六、最佳实践配置示例 📚

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
-   合理使用泛型

## 状态管理

-   小型项目使用 Context + useReducer
-   大型项目推荐使用 Redux Toolkit
-   遵循不可变数据原则
-   合理划分 state 结构

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 类型声明
- 组件实例类型
- 响应式类型

## 状态管理

- 小型项目使用 provide/inject
- 大型项目使用 Pinia
- 模块化状态管理
- 合理使用 storeToRefs

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 系统带来了:

✅ 更好的规则管理 ✅ 更强的扩展能力 ✅ 更棒的使用体验

虽然配置上稍微复杂了一点,但带来的收益是显而易见的。相信随着后续版本的更新,会有更多强大的特性推出!

参考资料

如果觉得文章有帮助就点个赞吧!也欢迎在评论区分享你的使用心得~ 😘