PatrickJS/awesome-cursorrules · 上手攻略

  • 仓库：PatrickJS/awesome-cursorrules
  • 链接：https://github.com/PatrickJS/awesome-cursorrules
  • 分类：skill
  • 作者：Jay
  • 更新：2026-07-14

是什么

awesome-cursorrules 是一个聚合 Cursor AI 编辑器 .mdc 规则文件的精选列表仓库。Cursor AI 是基于 AI 的代码编辑器（类似 VS Code + AI 助手），.cursor/rules/ 目录下的 .mdc 文件（Markdown + Cursor 扩展）定义项目级指令，告诉 Cursor AI 在特定项目、文件类型、框架和工作流中如何表现。简单说，它就是 Cursor 的"项目规范配置合集"。

仓库收录了大量框架、语言、工具的 .mdc 规则，涵盖前端、后端、移动端、游戏、测试、数据库、安全等几乎所有开发领域，直接 Copy 到项目里就能用。

解决什么问题

Cursor AI 虽然能写代码，但它默认依赖通用知识，不了解你项目的具体架构、命名规范、技术栈偏好。awesome-cursorrules 解决了三个问题：

  1. 项目级定制：把项目的技术栈规范（Next.js + TypeScript + Tailwind 组合）、目录结构要求、API 调用规范写入 .mdc 文件，让 Cursor 生成更贴合项目的代码。
  2. 团队一致性：所有成员共享同一套 .cursor/rules/*.mdc，AI 生成的代码风格、测试规范、安全要求保持一致，减少 code review 的摩擦。
  3. 减少重复修改：好的规范文件让 Cursor 一次生成到位，减少"生成→修改→再生成"的循环。

快速上手

第一步：安装 Cursor AI

从 https://cursor.sh/ 下载安装 Cursor 编辑器。

第二步：在项目中创建规则目录

mkdir -p .cursor/rules

第三步：挑选并添加 .mdc 规则文件

从本仓库（https://github.com/PatrickJS/awesome-cursorrules/tree/main/rules）挑选适合的 .mdc 文件，复制内容到 .cursor/rules/ 目录中。

例如，添加 Next.js 15 + React 19 + TypeScript + Tailwind 规则：

# 下载规则文件
curl -fsSL \
  "https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs15-react19-vercelai-tailwind-cursorrules-prompt-file.mdc" \
  -o .cursor/rules/nextjs15-react19-vercelai-tailwind.mdc

第四步：在 Cursor 中使用

打开 Cursor，重新加载项目（Cmd/Ctrl + R 或重新打开文件夹），Cursor 会自动读取 .cursor/rules/ 下的所有 .mdc 文件。在聊天框中描述需求，Cursor 会结合规则文件中的上下文生成代码。

核心用法

.mdc 文件格式

.mdc 文件本质是 Markdown，但包含 Cursor 扩展的元数据。一个典型的 .mdc 文件结构：

---
description: Next.js 15 项目规则
---

# 角色定义
你是一位 Next.js 15 专家，熟悉 App Router、React 19 和 TypeScript。

# 代码规范
- 始终使用 Server Components，除非明确需要客户端交互
- 使用 `next/font` 加载字体，禁止使用外部 CDN 字体
- 组件文件放在 `components/` 目录，按页面组织

# 目录结构
src/
  app/          # App Router 页面
  components/   # React 组件
  lib/          # 工具函数
  types/        # TypeScript 类型定义

# 注意事项
- 禁止在客户端组件中使用 `use client` 声明除非必要
- API 路由统一返回 NextResponse 对象

规则文件分类（主要类别）

类别 示例规则
前端框架 Next.js 15、React 18/19、Astro、Vue 3、Nuxt 3、Svelte 5、Angular、Qwik
后端/全栈 Cloudflare Workers、Convex、Deno、FastAPI、Node.js
移动开发 React Native、Flutter、Expo
数据库/API PostgreSQL、MongoDB、REST API、GraphQL
测试 Vitest、Jest、Playwright、Testing Library
CSS/样式 Tailwind CSS、Radix UI、shadcn/ui
语言 TypeScript、Python、Rust、Go
安全 Supabase Security Rules、通用安全规范

多规则组合

可以在同一项目中添加多个 .mdc 文件：

.cursor/rules/
  nextjs-typescript-tailwind.mdc    # Next.js 技术栈规范
  testing-best-practices.mdc         # 测试规范
  supabase-security.mdc              # Supabase 安全规范
  typescript-strict.mdc              # TS 严格模式规范

Cursor 会综合所有规则文件的内容生成代码。

规则优先级和覆盖

Cursor 按文件名字母顺序加载规则，后加载的规则可以覆盖先前的规则。如果两条规则冲突，可在文件名中加数字前缀控制加载顺序（如 00-base.mdc、01-nextjs.mdc）。

典型适用场景

  • 新项目初始化：用 .mdc 规范确保团队代码风格统一，减少初期规范讨论成本
  • 技术栈切换：从 Vue 迁移到 React 或 Next.js，添加对应规则文件让 Cursor 快速适应新技术
  • Code Review 准备：通过规则文件提前约束 AI 生成的代码质量，减少 review 轮次
  • 大型团队协作：统一的 .cursor/rules/ 配合 Git 管理，确保所有成员使用相同的 AI 辅助规范
  • 安全敏感项目：使用专门的 .mdc 规则（如 Supabase Security Rules）约束 AI 不产生安全漏洞

坑与注意

  1. .mdc 文件格式依赖 Cursor 版本：.mdc 格式（--- 包裹的 frontmatter）是 Cursor 较新版本引入的，旧版 Cursor 使用 .cursorrules 纯文本格式。确认你的 Cursor 版本支持 .mdc。
  2. 规则冲突：多个规则文件同时定义同一规范时可能冲突，通过文件名前缀控制加载顺序，并在规则中明确标注优先级。
  3. 规则粒度选择：不要把所有规范写进一个 .mdc 文件，按领域拆分更易于维护和复用。
  4. AI 幻觉仍然存在：规则文件能约束行为但不能完全消除幻觉；安全敏感的代码仍需人工 review。
  5. 规则仓库同步延迟：本仓库收录的规则可能不是框架最新版本，使用前建议对照官方文档核验关键配置项（如新版本 Next.js 的改动）。
  6. 中文项目适配：大部分规则文件为英文，且基于英语技术博客语境；直接用于中文项目时需适当调整注释和示例的语境描述。
  7. 不适用于所有 AI 助手：.mdc 是 Cursor 专用格式，其他 AI 助手（Claude Code、Copilot）需要转换为各自的提示文件格式。

与同类对比

特性 awesome-cursorrules Cursor 内置规则 Claude Code 提示 Copilot Labs
规则数量 200+ 个 .mdc 有限 自定义 有限
框架覆盖 全栈各领域 通用 按需自写 通用
开源可改 ✅ ❌ ✅ ❌
多框架组合 ✅ ✅ ✅ ❌
设备端可用 ❌ 仅编辑器 ✅ ❌ ❌
维护活跃度 高（持续更新） 随版本更新 依赖个人 随 Copilot 更新

如果你使用 Cursor，需要快速为项目建立 AI 编码规范，awesome-cursorrules 是目前最全的规则库；如果用其他编辑器或 AI 工具，它的规则思路值得参考，但需要自行翻译为对应格式。

一句话推荐

用 Cursor 写项目时，awesome-cursorrules 是目前最值得收藏的规则库——从 Next.js 到 Flutter、从安全规范到测试实践，复制即用，大幅提升 AI 生成代码的命中率。