跳到主要内容

.cursorrules 配置完全指南：从入门到实战

.cursorrules 是一个放在项目根目录的纯文本文件，用来告诉 Cursor 的 AI 该怎么干活——用什么代码风格、用了什么框架、要避免哪些模式。你可以把它理解为一个项目专属的"系统提示词"，每次 AI 交互时都会被注入上下文。

在 Cursor 论坛 上，每周都有人问同一个问题：".cursorrules 到底怎么配？" 官方文档讲了大方向，但很多细节只有实际用久了才能体会到。这篇教程把社区踩过的坑和总结出来的经验整理成了一份可操作的指南。

Cursor 设置面板中的 Rules for AI 配置界面

三种规则机制对比​

这是论坛里被问得最多的问题。Cursor 其实有 三种 不同的规则机制，各自用途不同。

Rules for AI（全局规则）​

在 设置 > 通用 > Rules for AI 里配置。全局生效，不管你打开哪个项目都会加载。存在本地设置里，不属于任何项目目录。

适合放：

  • 个人编码偏好（"始终使用 TypeScript strict 模式"）
  • 所有项目通用的习惯
  • 模型行为调整（"回答简洁，除非被问到否则不要解释"）
Rules for AI（全局规则）
始终使用函数式组件 + TypeScript。
优先使用命名导出，不要用默认导出。
修复 bug 时先简要说明根因，再给出修复方案。

.cursorrules（项目级规则）​

在项目根目录放一个叫 .cursorrules 的文件。这是最经典的方式——一个纯文本或 markdown 文件，描述 AI 在这个项目里应该怎么工作。

适合放：

  • 项目特定的技术栈和约定
  • 团队共享规则（提交到 git）
  • 框架特定的模式（Next.js、Django、Rails 等）

.mdc 规则（新格式，支持范围控制）​

新格式。把 .mdc 文件放在 .cursor/rules/ 目录下，每个文件可以指定作用范围（比如只对某些文件类型生效），还能在 UI 里单独开关。

适合放：

  • 需要精细控制规则生效范围的大型项目
  • 不同目录有不同编码约定的项目
  • 想按需启用/禁用规则的团队
.mdc 规则的目录结构
.cursor/
  rules/
    react-components.mdc
    api-endpoints.mdc
    database.mdc
    testing.mdc

对比一览​

特性Rules for AI.cursorrules.mdc 规则
作用范围全局（所有项目）单个项目单个项目
存放位置Cursor 设置项目根目录.cursor/rules/
文件匹配不支持不支持支持按规则匹配
UI 开关支持不支持支持
通过 git 共享不行可以可以
多文件不行不行（单文件）可以
状态稳定稳定（旧版）推荐
提示

三种机制可以同时使用。Rules for AI 设个人基线，.cursorrules 或 .mdc 处理项目细节。冲突时，项目级规则优先级更高。

实战：写一个高效的 .cursorrules​

大多数教程让你用 markdown 写 .cursorrules，这没问题。但论坛用户 razbakov 提了一个很有说服力的观点：用 JSON 结构化格式比纯文本效果更好。原因很简单——LLM 解析结构化数据比解析散文更可靠，规则被遵守的概率更高。

下面是一个 Next.js + TypeScript 项目的真实 .cursorrules 配置：

.cursorrules
{
  "project": {
    "name": "My SaaS App",
    "stack": ["Next.js 14", "TypeScript", "Tailwind CSS", "Prisma"],
    "packageManager": "pnpm"
  },
  "conventions": {
    "naming": {
      "components": "PascalCase",
      "functions": "camelCase",
      "files": "kebab-case",
      "constants": "SCREAMING_SNAKE_CASE"
    },
    "imports": {
      "order": ["react", "next", "lib/*", "components/*", "相对路径"],
      "noCircularImports": true,
      "alias": "@/ 指向 src/"
    },
    "components": {
      "preferFunctional": true,
      "folderByFeature": true,
      "colocateStyles": true
    }
  },
  "rules": [
    "组件 props 必须定义 TypeScript 接口",
    "仅在组件需要交互或 hooks 时使用 'use client' 指令",
    "Next.js app router 下默认使用服务端组件",
    "禁止默认导出，全部使用命名导出",
    "API 路由放在 app/api/ 下，遵循 REST 规范",
    "数据库查询统一通过 lib/db.ts 中的 Prisma client",
    "错误处理：使用 try/catch 配合正确的错误类型，禁止吞掉错误",
    "环境变量必须在 env.ts 中用 zod 校验"
  ],
  "antiPatterns": [
    "禁止使用 'any' 类型——用 'unknown' 配合类型守卫收窄",
    "禁止在 page.tsx 中写业务逻辑",
    "禁止使用内联样式——用 Tailwind class 或 CSS Modules",
    "禁止使用 '../../' 这种相对路径——用 @/ 别名"
  ]
}

为什么 JSON 比纯文本更好​

用自然语言段落写规则时，AI 需要猜测你的意思。换成 JSON 后：

  • 每条规则都是独立的、无歧义的指令
  • AI 不用猜哪些是规则、哪些是背景信息
  • 按类别组织，维护起来更方便
  • 增删规则不会破坏整体格式

注意：如果你更喜欢 markdown，也没问题。核心思路是 结构化优于散文。即使在 markdown 里，也要用列表和清晰的标题，不要写成长篇大论。

Markdown 版本参考​

如果你觉得 JSON 太死板，下面这个 markdown 版本同样清晰有效：

.cursorrules（Markdown 版本）
# 项目规则

## 技术栈
- Next.js 14 (App Router)
- TypeScript (strict 模式)
- Tailwind CSS
- Prisma ORM

## 命名规范
- 组件：PascalCase（UserProfile.tsx）
- 工具函数：camelCase（formatDate.ts）
- 常量：SCREAMING_SNAKE_CASE（MAX_RETRY_COUNT）
- 文件名：kebab-case（user-profile.tsx）

## 硬性规则
- 全部使用命名导出
- 每个组件必须有 TypeScript 类型定义
- 默认使用服务端组件，必要时才加 'use client'
- 禁止使用 any 类型
- 环境变量用 zod 校验

## 目录结构
- 组件放在 src/components/[feature]/
- Hooks 放在 src/hooks/
- API 工具放在 src/lib/
- 类型定义放在 src/types/

偷懒大法：让 AI 自己写规则​

论坛用户 tomredman 分享了一个很实用的技巧：与其从零手写规则，不如用 Cursor 的 Agent 模式分析代码库，让它自动生成。

具体操作​

  1. 打开 Cursor 的聊天面板
  2. 切换到 Agent 模式
  3. 输入以下 prompt：
分析这个代码库，生成一份完整的 .cursorrules 文件。
请检查：
- 现有文件和目录结构
- package.json 依赖
- 配置文件（tsconfig、eslint、prettier 等）
- 现有代码模式和约定

输出一份 .cursorrules，要能准确反映这个项目已经在使用的约定。
用 JSON 格式，按类别组织：技术栈、命名规范、编码规则、反模式。
  1. 仔细检查输出——AI 会发现一些你自己都没意识到的模式
  2. 删掉不准确的部分，补充遗漏的内容
  3. 保存到项目根目录，文件名 .cursorrules
信息

这个方法对已经运行了一段时间、模式比较一致的项目效果最好。全新项目建议手动写，或者从模板开始改。

迭代优化​

别指望一次生成就完美。我的流程是这样的：

  1. 用 Agent 模式生成初稿
  2. 让 Cursor 写一个新组件来测试——它有没有遵循规则？
  3. 记录它偏离的地方，针对性地加规则
  4. 重复几次，直到输出 consistently 符合预期

整个过程大概 15-20 分钟，但能省掉后面几小时的"不对，不是这样，再改改"来回拉扯。

推荐资源​

不用从零开始。社区已经整理了不少规则库，值得一看：

cursor.directory​

cursor.directory 是一个按框架和语言分类的 .cursorrules 文件合集，也是论坛上最常被推荐的规则资源站。

cursorrules.agnt.one​

cursorrules.agnt.one 专注于 Agent 模式相关的规则。如果你重度使用 Agent 模式，可以看看。

GitHub 上的真实项目​

在 GitHub 搜索 .cursorrules，能找到大量真实项目的配置：

GitHub 搜索语法
filename:.cursorrules stars:>5

按语言或框架过滤，找和你项目类似的。

论坛帖子：分享你的 .cursorrules​

Cursor 论坛 上有一个置顶帖叫 "Share your .cursorrules"，用户们会在里面贴自己的配置并解释为什么这么写。想看生产环境怎么用规则的，逛这个帖子就对了。

注意

不要直接复制别人的 .cursorrules 到自己项目里。一定要根据你的实际技术栈和约定做调整。一个 React Native 的规则文件放到 Django 项目里只会帮倒忙。

踩坑记录​

翻了论坛几十个帖子，以下是出现频率最高的问题：

1. 规则太长反而效果差​

很多人以为规则写得越多，AI 表现越好。恰恰相反。Cursor 会把你的规则注入上下文窗口，和代码、对话一起占空间。规则越长，留给实际代码上下文的空间越少。

尽量控制在 2000 字符以内。如果超过 5000，必须狠心删减。

反面教材：太啰嗦
当你在本项目中编写 React 组件时，你应该始终确保使用函数式组件而不是类组件，
并且你应该使用 TypeScript 接口而不是 PropTypes 来定义你的属性类型，
你还应该...
正面教材：简洁直接
- 只用函数式 React 组件
- 所有 props 用 TypeScript 接口定义
- 命名导出，不要默认导出

2. 规则冲突​

全局 Rules for AI 和项目级 .cursorrules 同时存在时，冲突在所难免。比如：

  • 全局规则："使用 2 空格缩进"
  • 项目规则："使用 4 空格缩进"

Cursor 会优先采用项目级规则，但 AI 在两边指令同时存在时还是会困惑。解决办法：全局规则尽量精简通用，具体细节放项目文件里。

3. 告诉 AI 它本来就会的事​

别把规则配额浪费在模型默认就能做好的事情上：

不需要写的规则
- 写干净、可读的代码          # 模型默认就会
- 遵循最佳实践               # 太模糊，没用
- 使用正确的错误处理          # 已经是默认行为了
- 给代码加注释                # 往往是噪音

应该聚焦在让项目 区别于默认行为 的地方：

真正有价值的规则
- 所有 API 输入用 Zod schema 校验
- 数据库查询统一走 repository 模式
- GraphQL resolver 必须加 @authenticated 指令
- monorepo 用 pnpm workspaces 管理

4. 忘了把 .cursorrules 提交到 git​

如果你在团队里工作但 .cursorrules 没进版本控制，那就只有你一个人受益。把它加到 git 里，作为新人 onboarding 的一部分。

把 .cursorrules 加入 git
git add .cursorrules
git commit -m "添加项目 AI 规则配置"

注意：有些团队更倾向于不把 .cursorrules 放进 git，因为不同开发者有不同偏好。这种情况下，可以用 .cursorrules.example 做模板，然后把 .cursorrules 加到 .gitignore。

5. 写完不测试​

写完规则后立刻测试。让 Cursor 做以下几件事：

  • 生成一个新组件
  • 重构一个现有函数
  • 修复一个 bug

如果输出和预期不符，说明规则需要调整。别等到深入开发某个功能时才发现规则没生效。

快速上手清单​

第一次配 .cursorrules？按这个最小路径走：

  • 决定用 .cursorrules（单文件）还是 .mdc（多文件）
  • 用 Agent 模式分析代码库，生成初稿
  • 精简到 2000 字符以内
  • 聚焦项目特有规则，不写泛泛而谈的内容
  • 让 Cursor 生成一个组件或函数来测试
  • 反复迭代直到输出稳定
  • 提交到版本控制
  • 分享给团队

相关文章​