Cursor 配置全攻略：从 .cursorrules 到 .mdc 规则体系实战

1. 为什么大多数人用 Cursor 只发挥了它三成实力

我身边不少朋友都在用 Cursor，但聊下来发现一个很普遍的现象：大家基本只把它当成一个"能自动补全的编辑器"，写代码时按 Tab 接受建议，偶尔用 Cmd+K 让它改改函数，然后就没了。问他们有没有配过.cursorrules，十个人里八个反问我"那是什么"。

这就是问题所在。Cursor 真正的威力不在于它的补全速度，而在于它能不能理解你的项目上下文、遵守你的编码习惯、记住你的技术栈偏好。而这些，全靠配置文件来约束。没有配置的 Cursor，就像一个技术很强但完全不了解你项目的新同事——能力有，但每次都要从头解释一遍背景，效率自然上不去。

我自己从去年开始系统性地折腾 Cursor 的配置体系，中间踩了不少坑，也总结出一套相对成熟的规则。配好之后最直观的感受是：重复性的样板代码基本不用自己敲了，AI 生成的代码风格和我手写的几乎一致，改需求时它也不会再给我推荐那些我根本不用的库。这篇文章就把这套配置思路完整拆开讲，从规则文件怎么写、忽略文件怎么配、到中文回复怎么设置，尽量让不同基础的人都能直接抄作业。

需要先说明的是，Cursor 的配置体系这两年一直在演进，早期主要靠根目录的.cursorrules单文件，后来逐步转向.cursor/rules/*.mdc这种分文件、带元数据的结构。两种方式目前都还能用，但新项目我强烈建议直接上.mdc方案，灵活性和可维护性完全不是一个量级。下面会分别讲清楚。

2. 规则文件的两代方案：从 .cursorrules 到 .cursor/rules

2.1 单文件 .cursorrules 的适用边界

.cursorrules是 Cursor 最早支持的规则载体，位置就在项目根目录，纯文本或 Markdown 格式都行。它的工作逻辑很简单：每次你向 AI 发起请求时，这个文件的全部内容会被塞进系统提示词里，作为"项目背景"一起发给模型。

这种方式的优点显而易见——简单直接，一个文件搞定，不用管目录结构。对于个人小项目、临时脚本、或者只是想快速试水的人，.cursorrules完全够用。我早期做几个小工具时就是这么干的，写个二三十行的规则，把技术栈和代码风格说清楚，效果立竿见影。

但它的短板也很明显。首先是全量注入：不管你这次是改前端组件还是写数据库迁移脚本，整个文件都会被塞进上下文，规则一多就浪费 token，还可能互相干扰。其次是无法分场景：你没法告诉 Cursor"写 React 组件时遵守这套规则，写 Node 脚本时遵守那套规则"。最后是团队协作困难：一个文件几十上百行，多人维护时冲突频繁，改一行都要 review 半天。

所以我的判断是：.cursorrules适合个人快速起步，一旦项目超过中等规模、或者要多人协作，就该考虑迁移了。

2.2 .cursor/rules/*.mdc 的分层设计逻辑

.cursor/rules/目录下的.mdc文件是现在的主流方案。每个.mdc文件由两部分组成：顶部的 YAML 元数据（frontmatter）和下面的规则正文。元数据决定了这条规则什么时候生效，正文决定了生效时说什么。

一个典型的.mdc文件长这样：

--- description: React 组件编写规范 globs: ["src/components/**/*.tsx"] alwaysApply: false --- - 所有组件使用函数式写法，禁止 class 组件 - Props 必须用 interface 显式声明类型 - 样式统一用 Tailwind，不写独立 CSS 文件 - 组件文件名用 PascalCase，与组件名一致

这里几个字段的含义需要说清楚，因为它们是整套体系的核心：

alwaysApply: true的规则相当于全局约束，比如"始终用中文回复""代码注释用中文"这类。而带globs的规则只在编辑匹配文件时激活，比如你只在写.tsx时才需要 React 规范，写.sql时就不该被它干扰。

这种分层设计的好处是精准投喂。AI 每次拿到的上下文都是和当前任务强相关的，既省 token 又减少误判。我实测下来，同样的模型，用.mdc分层规则生成的代码，符合项目规范的比例比单文件.cursorrules高出不少，尤其是大型项目里差异非常明显。

2.3 迁移时最容易忽略的元数据陷阱

从.cursorrules迁到.mdc时，很多人会直接把原来的内容复制过去，然后随便加个 frontmatter 就完事。这里有个坑我踩过：globs写错会导致规则完全不生效，而且没有任何报错提示。

比如你写globs: ["src/components/*.tsx"]，注意这里只有一个星号，它只能匹配src/components/下一层的文件，子目录里的文件全部漏掉。正确写法应该是src/components/**/*.tsx，双星号才能递归匹配所有层级。这个细节文档里提得不多，但实际影响很大——你会以为规则配好了，结果 AI 该不听话还是不听话。

另一个陷阱是alwaysApply和globs同时存在时的优先级。如果你设了alwaysApply: true，那globs基本就失去意义了，规则会无条件生效。所以全局规则和场景规则一定要分文件写，别混在一起。

提示：改完.mdc文件后，建议新开一个对话测试规则是否生效，因为已经加载的上下文可能还带着旧规则，容易让你误判。

3. 让 AI 真正听懂你的项目：规则内容的写法

3.1 技术栈声明要具体到版本和库

规则文件里最基础的一块是技术栈声明。但我发现很多人写得太笼统，比如只写"这是一个 React 项目"。这种信息对 AI 来说几乎没用，因为 React 生态太庞大了，它不知道该用哪个路由、哪个状态管理、哪个 UI 库。

正确的写法是把关键依赖和版本都列清楚：

## 技术栈 - 框架：Next.js 14（App Router，不用 Pages Router） - 语言：TypeScript 5.3，strict 模式开启 - 样式：Tailwind CSS 3.4 + shadcn/ui 组件库 - 状态：Zustand，不用 Redux - 数据请求：TanStack Query v5 - 表单：react-hook-form + zod 校验

这样写的好处是，当你说"帮我加一个用户列表页"时，AI 会直接用 App Router 的目录约定、用 shadcn 的 Table 组件、用 TanStack Query 拉数据，而不是给你生成一堆需要手动改的代码。我对比过，技术栈写得越具体，AI 一次生成就能用的概率越高，返工次数明显下降。

3.2 用"禁止清单"比"推荐清单"更有效

这是个反直觉的经验。一开始我写规则时，习惯列一堆"推荐做法"，比如"推荐使用函数式组件""推荐用 const 声明"。但实测下来，明确禁止某些做法，比推荐某些做法效果更好。

原因在于，推荐是开放的，AI 可能理解成"优先但不强制"，遇到它觉得更"优雅"的写法时还是会偏离。而禁止是封闭的，边界清晰，AI 更容易遵守。所以我现在写规则，会专门留一个"禁止"区块：

## 禁止事项 - 禁止使用 any 类型，不确定时用 unknown 加类型守卫 - 禁止在组件内直接写 fetch，统一走 api 层封装 - 禁止使用 index 作为列表 key - 禁止提交 console.log，调试用 logger 工具 - 禁止引入 lodash，工具函数自己写或从 utils 引

这份清单是我根据团队实际 code review 中最常打回的问题整理的。把它写进规则后，AI 生成的代码在 review 阶段被挑刺的次数少了一大截。你可以观察自己项目里 review 时反复出现的问题，把它们沉淀成禁止清单，这是投入产出比最高的规则内容。

3.3 代码风格规则要给出正反例

光说"用 PascalCase 命名组件"还不够，因为 AI 对命名规范的理解可能和你有偏差。更稳妥的做法是给出正例和反例，让它有明确的参照。

## 命名规范 组件文件：UserProfile.tsx（正例）/ userProfile.tsx（反例） 工具函数：formatDate.ts（正例）/ FormatDate.ts（反例） 常量：MAX_RETRY_COUNT（正例）/ maxRetryCount（反例）

这种正反例对照的写法，比单纯描述规则要精确得多。尤其是团队里有约定俗成但不好用文字描述的命名习惯时，举几个例子往往比写一段说明更管用。

3.4 把项目特有的业务约束写进去

这一块是很多人会忽略的，但恰恰是让 AI 生成代码"接地气"的关键。每个项目都有一些外人不知道的业务约束，比如：

• 金额字段统一用分为单位存储，展示时再除以 100
• 所有时间戳用 UTC，展示层再转本地时区
• 用户 ID 是雪花算法生成的 19 位数字，前端要用 string 接收避免精度丢失
• 接口返回统一包一层{ code, data, message }结构

这些约束如果不写进规则，AI 生成的代码很可能在细节上出错，比如把金额当元处理、把用户 ID 当 number 解析导致精度丢失。我吃过这个亏——有次 AI 生成的订单金额计算直接用了浮点数，测试时才发现精度问题，回头一查就是因为规则里没写清楚金额单位。

把这些业务约束单独整理成一个.mdc文件，用alwaysApply: true让它全局生效，能省掉大量后期调试。

4. .cursorignore 与上下文管理：别让 AI 看不该看的

4.1 .cursorignore 到底忽略什么

.cursorignore的作用和.gitignore类似，但针对的是 Cursor 的索引和上下文。写进去的路径，Cursor 在建立代码索引、检索上下文时会跳过，AI 也就"看不到"这些文件。

为什么需要这个？两个原因。第一是性能：如果项目里有node_modules、dist、build这些目录，全量索引会非常慢，而且这些文件对理解业务代码毫无帮助。第二是安全：.env、密钥文件、证书这类敏感内容，绝对不能让它们进入 AI 的上下文。

一个我常用的.cursorignore模板：

node_modules/ dist/ build/ .next/ coverage/ *.log .env .env.* *.pem *.key .DS_Store

4.2 忽略规则写错反而拖慢索引

这里有个细节值得单独说。.cursorignore的匹配规则和.gitignore类似，但不是完全一致。比如dist/和dist在某些情况下行为不同，前者明确指目录，后者可能匹配到同名文件。

更关键的是，如果你忽略的目录里其实有 AI 需要参考的文件，会导致它"断片"。我遇到过一次：把整个types/目录忽略了，结果 AI 生成代码时老是猜错类型定义，因为它根本看不到那些 interface。后来把types/从忽略列表移除，问题立刻消失。

所以忽略的原则是：只忽略生成物、依赖、敏感文件，源码和类型定义一律保留。拿不准的时候，宁可先不忽略，观察索引速度和 AI 表现，再逐步调整。

4.3 用 @ 引用精准控制单次上下文

除了全局忽略，Cursor 还支持在对话里用@手动引用文件或目录。这是精准控制上下文的好办法。比如你要改一个工具函数，可以@utils/format.ts把它拉进来，AI 就能基于真实代码来改，而不是凭空猜。

我的习惯是：涉及跨文件改动时，主动 @ 相关文件。比如改一个 API 调用，我会同时 @ 接口定义文件、调用方组件、以及类型文件。这样 AI 拿到的信息完整，生成的改动一次到位，不用来回追问。

配合.cursorignore的全局过滤和@的精准引用，基本能做到"该看的都看到，不该看的不打扰"，这是用好 Cursor 的核心手感。

5. 中文回复与界面汉化的完整设置路径

5.1 让 AI 用中文回复的三种方式

热词里"cursor设置中文回复""cursor怎么设置中文"出现频率很高，说明这是很多人的刚需。让 AI 用中文回复，主要有三种做法，效果和适用场景各不同。

第一种，在规则文件里声明。在alwaysApply: true的规则里加一句"始终使用简体中文回复，代码注释也用中文"。这是最推荐的方式，因为它跟着项目走，换设备、换协作者都生效。

第二种，在对话里直接要求。每次开新对话时说一句"请用中文回复"。缺点是每次都要说，容易忘。

第三种，改 Cursor 的界面语言设置。这个影响的是软件界面本身的语言，不是 AI 回复的语言，两者别搞混。界面汉化在设置里找 Language 相关选项切换即可，但 AI 回复语言还是得靠规则或对话指令控制。

我自己的做法是规则文件里写死中文回复，这样最省心。需要注意的是，代码本身（变量名、函数名）建议还是用英文，只让注释和解释用中文。混用中英文命名会让代码可读性变差，也不利于协作。

5.2 界面语言与 AI 回复语言是两回事

这一点必须强调，因为太多人混淆了。Cursor 的界面语言设置，改的是菜单、按钮、提示这些 UI 文案的显示语言。而 AI 在对话里用什么语言回复，取决于你给它的指令或规则。

我见过有人把界面切成中文后，发现 AI 还是用英文回复，就以为设置没生效。其实这俩根本不是一个开关。界面语言是软件本地化，AI 回复语言是模型行为，后者只能通过提示词控制。

所以正确的组合是：界面语言按自己习惯设，AI 回复语言在规则文件里声明。两件事分开处理，就不会困惑了。

5.3 中文规则本身也可能被"翻译"

还有个隐蔽的坑：如果你用中文写规则，AI 有时会在生成代码时把规则里的中文术语"翻译"成英文，导致命名不一致。比如规则里写"用户信息组件"，它可能生成UserInfoComponent而不是你期望的UserProfile。

解决办法是在规则里明确给出中英对照，尤其是涉及命名的部分：

## 术语对照 用户信息 → UserProfile 订单详情 → OrderDetail 支付记录 → PaymentRecord

这样 AI 就知道中文术语对应哪个英文命名，不会自由发挥。这个技巧在处理业务术语较多的项目时特别有用。

6. 实测中那些文档不会告诉你的坑

6.1 规则太多反而让 AI "精神分裂"

我一开始很兴奋，把能想到的规则全写进去了，结果发现 AI 反而变笨了——生成的代码时而遵守这条、时而忽略那条，风格飘忽不定。后来才明白，规则总量是有上限的，塞太多会稀释每条规则的权重，还可能互相冲突。

我的经验是：核心规则控制在 5 到 8 个.mdc文件，每个文件聚焦一个主题（技术栈、命名、禁止事项、业务约束等），单个文件正文别超过 100 行。宁可精炼，不要堆砌。真正重要的规则放alwaysApply，次要的用globs按需激活。

6.2 规则冲突时的优先级判断

当两条规则对同一件事给出不同要求时，AI 会怎么处理？实测下来，后加载的、更具体的规则通常优先。但这个行为不稳定，不同模型版本表现不一样。

所以最稳妥的做法是从源头避免冲突。写完规则后自己通读一遍，检查有没有自相矛盾的地方。比如一个文件说"用双引号"，另一个说"用单引号"，这种必须统一。我建议专门花时间做一次规则审查，把冲突项清理掉，比事后调试划算得多。

6.3 换模型后规则要重新验证

Cursor 支持切换不同的底层模型，而不同模型对规则的理解和遵守程度是有差异的。我遇到过同一个规则文件，在 A 模型下效果很好，换到 B 模型后 AI 就开始"选择性失忆"。

所以每次换主力模型后，建议拿几个典型任务测一下规则是否还生效。如果发现某些规则被忽略，可能需要调整措辞，把要求写得更明确、更靠前。这不是规则写错了，而是模型特性不同，需要适配。

6.4 规则文件也要进版本控制

最后一点，.cursor/rules/目录和.cursorignore都应该提交到 Git 仓库。这样团队成员拉下代码就自动获得统一的 AI 行为，新人不用单独配置，协作时生成的代码风格也一致。

我团队现在的做法是：规则文件由技术负责人维护，改动走正常的 PR 流程。谁发现 AI 生成的代码有共性问题，就提 PR 补充规则。这样规则库会随着项目推进不断沉淀，越用越顺手。

7. 一套可以直接抄的配置骨架

说了这么多原理和坑，最后给一套我自己在用的配置骨架，你可以直接拿去改。目录结构是这样的：

.cursor/ rules/ 00-global.mdc # 全局：中文回复、通用原则 01-tech-stack.mdc # 技术栈声明 02-naming.mdc # 命名规范 03-forbidden.mdc # 禁止事项 04-business.mdc # 业务约束 .cursorignore

00-global.mdc的内容示例：

--- description: 全局规则，始终生效 alwaysApply: true --- - 始终使用简体中文回复，代码注释用中文，变量和函数名用英文 - 回答简洁直接，不写客套话，代码优先 - 涉及不确定的 API 时，先说明假设再给代码

03-forbidden.mdc的内容示例：

--- description: 代码禁止事项 alwaysApply: true --- - 禁止 any 类型 - 禁止组件内直接 fetch - 禁止 index 作列表 key - 禁止提交 console.log - 禁止引入未在技术栈中声明的库

这套骨架我用了大半年，覆盖了日常开发绝大多数场景。你可以根据自己的项目往里加，但记住前面说的——别贪多，精炼比全面重要。

配置这件事没有一劳永逸的答案，项目在变、模型在变，规则也得跟着迭代。我的习惯是每个月抽半小时回顾一下规则文件，把最近 review 中反复出现的问题补进去，把已经内化成习惯的规则精简掉。这样维护下来，Cursor 会越来越懂你的项目，写代码时那种"它怎么知道我要这么写"的顺畅感，就是这么一点点攒出来的。