Skip to content
返回 AI 编程

Cursor 规则与 .cursorrules 配置

通过项目规则、忽略模式和上下文范围调优 Cursor 输出质量。

Cursor进阶

为什么

据 Sacra 估计，Cursor 在 2024 年 11 月达到 6500 万美元 ARR（同比增长 6400%），JetBrains 2026 年 1 月 AI Pulse 调查显示 18% 的专业开发者在工作中使用 Cursor。.cursorrules 是杠杆最高的 Cursor 配置。

它被注入每个提示词，因此几行精确内容即可重塑所有补全和聊天以匹配你的架构。没有它，Cursor 默认使用通用 Next.js/React 模式，与你的约定冲突并产生你拒绝的 diff。

何时使用

当 Cursor 建议不匹配项目约定时添加 .cursorrules：错误的导出风格、臆造的数据获取模式、或从错误层导入。新人使用 Cursor 时也用它，让他们无需翻文档即可继承约定。

如何做

1. 在项目根目录创建 .cursorrules（纯文本，纳入 git）。 2. 首先声明技术栈和版本固定： "Astro 7 静态站点，React 18 islands，Tailwind 3，TypeScript strict。" 3. 添加能阻止最常见错误建议的架构规则： - "数据位于 src/data/*.ts。绝不在组件中内联数据。" - "组件使用命名导出。仅 Astro 页面使用默认导出。" - "i18n：9 语言，en 在根路径，其余在 /{locale}/。使用 i18n 辅助函数。" 4. 添加匹配 lint 配置的风格规则： - "除页面外无默认导出。无 any。优先 type 而非 interface。" 5. 显式添加反模式（否定效果好）： - "不要用 useEffect 获取数据。数据仅构建时获取。" - "不要在组件中从 astro/data/* 导入；从 src/data/ 导入。" 6. 用 .cursorignore 限定上下文，将大型生成目录排除出索引： dist_astro/ node_modules/ *.min.js 7. 迭代。当 Cursor 给出错误建议时，加一行规则阻止它。 将 .cursorrules 视为活文档，在 PR 中审查。

示例

Astro + React 单仓的 .cursorrules： 你正在开发一个 Astro 7 静态站点，使用 React 18 islands。 构建：'npm run build'（tsc -b && astro build）。 - 数据事实源：src/data/*.ts。派生索引：astro/data/*Index.ts。 - 绝不在组件中内联数据；始终从 src/data/ 导入。 - 组件使用命名导出；仅 Astro 页面使用默认导出。 - i18n：9 语言，en 在根路径，其余在 /{locale}/。 - CSS：Tailwind 3，含 spark/ink 自定义色板。无 CSS modules。 - 无 any 类型。不用 useEffect 获取数据（仅构建时）。 - 不在组件中从 astro/data/* 导入。 .cursorignore： dist_astro/ node_modules/ coverage/ *.min.js

常见问题

  • ⚠Cursor 建议 `import x from 'nonexistent-pkg'` → 检查 package.json；若缺失运行 `npm install <pkg>` 并验证导入路径可解析。
  • ⚠错误：大文件出现 "Context window exceeded" 警告 → 用 @file 限定上下文，或结构变更后运行 Cmd+Shift+P → 'Cursor: Rebuild Index'。
  • ⚠错误：切换分支后 Tab 补全失效 → 运行 `git status` 后 Cmd+Shift+P → 'Cursor: Rebuild Index'；通常是索引过期。
  • ⚠技术栈升级后规则过期：在 Astro 7 上引用 Astro 4 的规则导致错误建议。大版本升级时更新。

最佳实践

  • ✓以技术栈和版本固定开头；它们锚定所有其他建议。
  • ✓将规则写为具体否定（'不要 X'）和具体肯定（'始终从 Z 做 Y'）。
  • ✓.cursorrules 保持在 20 行以内；长文档移至 CLAUDE.md 或 /docs。
  • ✓提交 .cursorrules 并在 PR 中审查变更，使团队对约定达成一致。
  • ✓Cursor 重复错误建议时立即加一条规则；修复根因而非症状。

常见问题解答

什么是 .cursorrules，放在哪里？

项目根的纯文本文件，内容注入每个 Cursor 提示词。几行精确内容即可重塑所有补全和聊天以匹配你的架构。纳入 git 让全团队共享相同规则。

.cursorrules 和 CLAUDE.md 有何不同？

.cursorrules 是 Cursor 专用，注入每个 Cursor 提示词。CLAUDE.md 由 Claude Code 读取。两者为不同工具服务同一目的（项目约定）——很多团队保持两者同步，或从一个生成另一个。

.cursorrules 该多长？

硬规则保持在约 20 行以内。50 行文件稀释注意力。以技术栈和版本固定开头，然后具体肯定（'始终从 src/data/ 导入'）和否定（'不用 useEffect 获取数据'）。长文档移至 /docs。

.cursorignore 有什么用？

列出 Cursor 不应索引的路径（dist/、node_modules/、*.min.js、coverage/）。将大型生成目录排除出索引可节省上下文并加速索引。没有它，构建产物污染检索并浪费上下文预算。

如何阻止 Cursor 建议 Next.js 模式？

在 .cursorrules 加显式技术栈和反模式规则：'Astro 7 静态站点，无 Next.js'、'数据仅构建时，不用 useEffect 获取'、'除页面外命名导出'。无规则时 Cursor 默认 Next.js/React；精确规则覆盖默认。