.cursorrules 配置文件详细讲解

2025-03-29

总字数: 1.7k字 | 阅读时长: 7分

.cursorrules 文件说明

.cursorrules 文件是 Cursor 编辑器的配置文件，用于定义代码库的特定规则和行为。
.cursorrules 文件使用 JSON 格式编写，通常放置在项目根目录下。基本结构如下：

{
  "ignore": ["node_modules", "dist", ".git"],
  "defaultLLM": "claude-3-opus",
  "customCommands": [
    {
      "name": "生成测试",
      "prompt": "为当前文件生成单元测试",
      "key": "ctrl+shift+t"
    }
  ],
  "fileAssociations": {
    "*.vue": "vue"
  }
}

常用配置项

ignore: 指定 Cursor 应忽略的文件或目录
defaultLLM: 设置默认使用的大语言模型
customCommands: 定义自定义 AI 命令
fileAssociations: 指定特定文件扩展名应使用的语言模式

完整的 .cursorrules 常用配置文件示例

{
  "ignore": [
    "node_modules",
    "dist",
    ".git",
    "build",
    "coverage",
    "*.min.js",
    "*.log",
    "tmp"
  ],
  "defaultLLM": "claude-3-sonnet",
  "customCommands": [
    {
      "name": "生成测试",
      "prompt": "为当前文件生成单元测试，使用Jest框架",
      "key": "ctrl+shift+t"
    },
    {
      "name": "优化代码",
      "prompt": "分析当前代码并提供性能优化建议",
      "key": "ctrl+shift+o"
    },
    {
      "name": "添加注释",
      "prompt": "为当前函数添加详细的JSDoc风格注释",
      "key": "ctrl+shift+c"
    },
    {
      "name": "重构代码",
      "prompt": "重构当前代码以提高可读性和可维护性",
      "key": "ctrl+shift+r"
    }
  ],
  "fileAssociations": {
    "*.vue": "vue",
    "*.jsx": "javascriptreact",
    "*.tsx": "typescriptreact",
    "*.astro": "astro",
    "*.svelte": "svelte"
  },
  "aiSettings": {
    "temperature": 0.7,
    "contextWindow": 10000,
    "maxTokens": 2000
  },
  "editorSettings": {
    "formatOnSave": true,
    "tabSize": 2,
    "insertSpaces": true,
    "wordWrap": "on"
  },
  "projectInfo": {
    "name": "我的项目",
    "description": "这是一个React前端项目，使用TypeScript开发",
    "framework": "React",
    "codingStyle": "函数式组件，使用hooks管理状态"
  },
  "codeGeneration": {
    "preferredLanguage": "typescript",
    "testFramework": "jest",
    "styleFramework": "tailwindcss"
  }
}

1. ignore

"ignore": [
  "node_modules",
  "dist",
  ".git",
  "build",
  "coverage",
  "*.min.js",
  "*.log",
  "tmp"
]

作用：指定 Cursor 在进行代码分析、搜索和 AI 操作时应忽略的文件和目录。
详解：

可以使用确切的文件/目录名称（如 “node_modules”）
支持通配符（如 “*.min.js”）匹配特定模式的文件
忽略大型或不相关的目录可以提高 Cursor 的性能
通常应忽略构建输出、依赖项、日志文件和临时文件

2. defaultLLM

"defaultLLM": "claude-3-sonnet"

作用：设置项目默认使用的大语言模型。
详解：

可选值包括 “claude-3-opus”、”claude-3-sonnet”、”gpt-4”等
不同模型有不同的能力和速度特性
可以根据项目复杂度和需求选择合适的模型
更高级的模型（如 opus）理解能力更强但可能速度较慢

3. customCommands

"customCommands": [
  {
    "name": "生成测试",
    "prompt": "为当前文件生成单元测试，使用Jest框架",
    "key": "ctrl+shift+t"
  },
  // 其他命令...
]

作用：定义可通过快捷键触发的自定义 AI 命令。
详解：

name：命令的显示名称，会出现在命令面板中
prompt：发送给 AI 的指令文本
key：触发命令的键盘快捷键
可以创建多个命令用于不同的开发任务
命令可以针对特定框架或库（如示例中的 Jest）

4. fileAssociations

"fileAssociations": {
  "*.vue": "vue",
  "*.jsx": "javascriptreact",
  "*.tsx": "typescriptreact",
  "*.astro": "astro",
  "*.svelte": "svelte"
}

作用：指定特定文件扩展名应使用的语言模式。
详解：

帮助 Cursor 正确识别和处理特定文件类型
确保语法高亮和代码分析正确应用
对于新兴框架或自定义文件类型特别有用
键是文件模式（支持通配符），值是语言标识符

5. aiSettings

"aiSettings": {
  "temperature": 0.7,
  "contextWindow": 10000,
  "maxTokens": 2000
}

作用：配置 AI 生成行为的参数。
详解：

temperature：控制输出的随机性（0-1），较低值产生更确定性的输出
contextWindow：AI 考虑的上下文窗口大小（以标记为单位）
maxTokens：AI 响应的最大长度
这些设置影响 AI 生成代码和回答问题的方式
较低的温度适合精确任务，较高的温度适合创意任务

6. editorSettings

"editorSettings": {
  "formatOnSave": true,
  "tabSize": 2,
  "insertSpaces": true,
  "wordWrap": "on"
}

作用：配置编辑器的行为和外观。
详解：

formatOnSave：保存时是否自动格式化代码
tabSize：制表符的空格数
insertSpaces：是否使用空格而非制表符
wordWrap：文本换行设置
这些设置可以覆盖全局编辑器设置，确保项目内一致的代码风格

7. projectInfo

"projectInfo": {
  "name": "我的项目",
  "description": "这是一个React前端项目，使用TypeScript开发",
  "framework": "React",
  "codingStyle": "函数式组件，使用hooks管理状态"
}

作用：提供项目的背景信息，帮助 AI 更好地理解上下文。
详解：

name：项目名称
description：项目简要描述
framework：使用的主要框架
codingStyle：项目的编码风格和约定
这些信息帮助 AI 生成更符合项目风格和需求的代码
对于团队协作和保持一致性很有价值

8. codeGeneration

"codeGeneration": {
  "preferredLanguage": "typescript",
  "testFramework": "jest",
  "styleFramework": "tailwindcss"
}

作用：指定代码生成的偏好设置。
详解：

preferredLanguage：首选编程语言
testFramework：使用的测试框架
styleFramework：使用的样式/CSS框架
这些设置指导 AI 在生成代码时使用特定的技术栈
确保生成的代码与项目的其余部分保持一致
减少了手动调整生成代码的需要

总结

.cursorrules 文件通过这些配置项，可以高度定制 Cursor 编辑器在特定项目中的行为。这不仅提高了开发效率，还确保了团队成员之间的一致性，并使 AI 生成的代码更好地符合项目需求和风格。根据项目的具体需求，你可以选择性地使用这些配置项，创建最适合你的开发环境。

阅读量