05_Cursor之自定义规则与配置

关键字.cursorrules, 自定义规则, AI模型配置, 文档集成, 终端集成, Cursor配置05_Cursor之自定义规则与配置Cursor知识体系Cursor知识体系续 | -- 配置定制层 | -- .cursorrules规则文件 | | -- 项目编码规范 | | -- 风格指南 | | -- 命名约定 | | -- 架构模式 | | | -- 规则配置位置 | | -- 全局规则 | | -- 项目规则 | | -- AI Rules设置 | | | -- 自定义AI模型 | | -- 模型选择 | | -- API配置 | | -- 按任务选择模型 | | | -- 文档集成 | | -- 库文档引用 | | -- 自定义文档 | | -- API参考 | | | -- 终端集成 | -- 错误消息处理 | -- 堆栈跟踪分析 | -- 修复建议引言Cursor的默认配置对于大多数开发者来说已经足够好。但如果你想要更精准的AI输出、更符合项目风格的代码生成、更高效的个性化工作流自定义配置是必经之路。这篇文章将系统性地介绍Cursor的各种配置选项从.cursorrules规则文件到AI模型配置从文档集成到终端集成帮助你打造一个真正属于你的AI编程环境。一、.cursorrules规则文件1.1 什么是.cursorrules.cursorrules是一个位于项目根目录的配置文件用于定义AI在项目中的行为规范。你可以把它理解为给Cursor看的项目风格指南。项目结构 ------------------------------------------ | 项目根目录/ | | -- .cursorrules -- AI规则配置 | | -- src/ | | -- package.json | | -- ... | ------------------------------------------.cursorrules的内容会被Cursor的AI系统自动读取和遵循。设置了.cursorrules后Cursor生成的代码会自动符合项目的编码规范。1.2 规则文件格式.cursorrules使用简单的文本格式可以用自然语言描述规则.cursorrules示例 # 项目编码规范 ## 语言 - 使用TypeScript禁止使用原生JavaScript - 严格模式开启strict: true ## 命名规范 - 变量和函数camelCase - 类和类型PascalCase - 常量UPPER_SNAKE_CASE - 文件名kebab-case.ts ## 函数规范 - 所有函数必须包含TypeScript类型标注 - 使用JSDoc注释导出函数 - 箭头函数优先除非需要this绑定 ## React规范 - 使用函数组件 Hooks - 组件文件使用PascalCase命名 - Props类型使用ComponentNameProps命名 ## 错误处理 - 使用自定义Error类 - 异步函数必须try-catch - API调用必须有错误处理 ## 代码风格 - 使用2空格缩进 - 单引号字符串 - 分号结尾 - 使用Prettier格式化 1.3 实际使用示例场景一TypeScript项目# TypeScript严格模式项目规则 ## 类型系统 - 启用strict模式 - 禁止使用any类型使用unknown代替 - 禁止隐式类型转换 - 使用联合类型和交叉类型 ## 接口vs类型别名 - 数据结构使用interface - 复杂类型使用type别名 - 优先使用interface扩展 ## 导入规则 - 使用named imports优于默认导入 - 按类型导入使用import type - 相对导入优先于路径别名 ## 示例代码风格 typescript interface User { id: string; name: string; email: string; } type UserRole admin | editor | viewer; async function fetchUser(id: string): PromiseUser { const response await api.getUser(/users/${id}); return response.data; }**场景二React项目**React项目规则组件规范只使用函数组件使用Hooks管理状态和副作用使用React.FC标注组件类型命名规范组件PascalCaseHooksuse前缀工具函数camelCaseCSS类名BEM或Tailwind类Props规范组件Props必须定义接口使用children prop代替插槽必需prop放在可选prop前面状态管理组件本地状态用useState跨组件状态用Context复杂状态考虑useReducer示例interface ButtonProps { label: string; onClick: () void; variant?: primary | secondary; children?: never; // 本组件不使用children } export const Button: React.FCButtonProps ({ label, onClick, variant primary }) { return ( button className{btn btn-${variant}} onClick{onClick} {label} /button ); };**场景三Python项目**Python项目规则代码风格遵循PEP 8使用Black格式化使用isort排序导入类型标注所有公共函数必须有类型标注使用typing模块的类型优先使用类型别名文档注释使用docstring描述函数Google风格docstring测试使用pytest测试文件以test_开头使用fixture管理测试数据示例fromtypingimportList,Optionaldefcalculate_average(numbers:List[float])-Optional[float]:Calculate the average of a list of numbers. Args: numbers: List of numeric values. Returns: The average value, or None if list is empty. Raises: TypeError: If input is not a list of numbers. ifnotnumbers:returnNonereturnsum(numbers)/len(numbers)### 1.4 规则优先级 Cursor的规则生效优先级如下优先级从高到低Composer中的临时指令.cursorrules文件Cursor设置中的全局规则Cursor默认行为这意味着你可以 - 在Composer中使用临时规则覆盖项目规则 - 设置项目级别的.cursorrules供团队共用 - 设置个人偏好作为全局规则 ## 二、规则配置位置 ### 2.1 设置入口 规则配置有两个主要入口 **入口一Settings → General → AI Rules**Cursor设置±-----------------------------------------| Settings || ±---------------------------------------|| | General || | ±-------------------------------------|| | | [ ] Enable AI Features || | | || | | AI Rules || | | ±--------------------------------- || | | | 全局AI规则编辑器 | || | | | 适用于所有项目 | || | | ±--------------------------------- || | | || | | Rule Priority || | | [项目规则优先] [全局规则优先] || | ±-------------------------------------|| ±---------------------------------------|±-----------------------------------------**入口二项目根目录的.cursorrules文件** 项目根目录的.cursorrules文件会被自动加载适用于该项目的所有AI交互。 ### 2.2 全局规则 vs 项目规则 **全局规则**Settings → AI Rules - 适用于你在Cursor中打开的所有项目 - 适合设置个人编码偏好 - 跨项目保持一致性 **项目规则**.cursorrules - 只适用于特定项目 - 适合设置团队共同的编码规范 - 可以随项目版本控制 **最佳实践**推荐配置策略全局规则基础代码风格缩进、引号等通用TypeScript/JavaScript规则个人偏好设置项目规则.cursorrules团队编码规范项目特定约定技术栈要求## 三、自定义AI模型 ### 3.1 模型选择 Cursor支持多个AI模型你可以在不同场景下选择不同模型 **Settings → Models配置界面**±-----------------------------------------| Models Settings |±-----------------------------------------| Default Model || ±------------------------------------- || | [Claude 3.5 Sonnet v] | || ±------------------------------------- || || Per-Task Model Selection || ±------------------------------------- || | Tab Completion | || | [Cursor Fast (default) v] | || | | || | Chat | || | [Claude 3.5 Sonnet v] | || | | || | Composer | || | [GPT-4o v] | || ±------------------------------------- |±-----------------------------------------### 3.2 添加自定义模型 除了内置模型你还可以添加第三方模型添加自定义模型步骤获取API密钥OpenRouterOpenAI兼容APIAnthropic API配置模型Settings → Models → Add Model填写配置模型名称API端点API密钥上下文窗口大小### 3.3 模型对比与选择建议 | 模型 | 特点 | 推荐使用场景 | |------|------|-------------| | Claude 3.5 Sonnet | 代码理解深解释清晰 | 复杂重构代码审查 | | GPT-4o | 能力全面多模态 | 通用任务图像理解 | | GPT-4 Turbo | 速度快 | 日常补全快速任务 | | Cursor Fast | 极速 | 简单补全Tab预测 | | 自定义模型 | 可配置 | 企业场景特定需求 | ### 3.4 API配置 对于自定义模型你需要配置API json // 自定义模型配置示例 { models: [ { name: My-Custom-Model, apiKey: sk-xxxxx, baseUrl: https://api.openrouter.ai/v1, model: anthropic/claude-3.5-sonnet, maxTokens: 4096, contextWindow: 200000 } ] }四、文档集成4.1 内置文档Cursor内置了大量流行库的文档可以直接查询React, Vue, AngularNode.js, ExpressPython, Django, FlaskTypeScript, JavaScript以及更多…4.2 添加自定义文档你可以添加项目特定的文档或内部库文档Settings → Documents → Add Document 配置项 - Document Name文档名称 - Document URL文档URL或本地路径 - File Pattern匹配的文件模式示例添加内部组件库文档文档配置 - 名称Internal UI Kit - URLhttps://docs.internal.company/ui-kit - 文件匹配src/components/ui/**/*4.3 文档使用在Chat中使用docs引用文档docs React Hooks 解释useEffect的正确用法包括清理函数的实现 docs TypeScript Handbook 如何使用泛型约束五、终端集成5.1 错误消息处理Cursor能够理解终端的错误输出并提供修复建议。使用方式在终端中运行命令出现错误复制错误消息粘贴到Cursor Chat中询问如何修复终端输出 ------------------------------------------ | $ npm run build | | | | ERROR in ./src/index.ts | | Module not found: Error: Cant resolve | | lodash in src | | ./src/index.ts:1:1 | ------------------------------------------ Cursor Chat ------------------------------------------ | 你如何修复这个错误 | | | | AI缺少lodash依赖。需要安装 | | npm install lodash | | npm install --save-dev types/lodash | ------------------------------------------5.2 堆栈跟踪分析对于运行时错误Cursor可以分析完整的堆栈跟踪错误堆栈跟踪 ------------------------------------------ | TypeError: Cannot read property map | | of undefined | | at Array.forEach (anonymous) | | at processItems (src/utils.ts:15) | | at main (src/index.ts:25) | ------------------------------------------ Cursor分析 ------------------------------------------ | AI分析 | | | | 问题位置src/utils.ts 第15行 | | | | 原因processItems函数接收的items参数 | | 为undefined可能的原因 | | | | 1. 调用时未传参 | | 2. 数据源返回undefined | | 3. 异步数据未正确等待 | | | | 建议修复方案... | ------------------------------------------5.3 针对性修复Cursor不仅解释错误还能直接生成修复代码请求修复这个Bug并解释原因 Cursor生成 typescript // 问题分析 // src/utils.ts 第15行试图对items调用forEach // 但items为undefined // 修复方案 export function processItems(items?: Item[]): ProcessedItem[] { // 添加参数校验 if (!items) { console.warn(processItems received undefined items); return []; } return items.map(item ({ ...item, processed: true })); }## 六、高级配置 ### 6.1 .cursorignore 类似于.gitignore.cursorignore用于排除不需要AI关注的文件.cursorignore示例±-----------------------------------------| /node_modules || /dist || /build ||.min.js || **/.test.ts || /coverage || /.cursor || /tmp |±-----------------------------------------### 6.2 快捷键自定义 Cursor支持自定义快捷键Settings → Keyboard Shortcuts自定义快捷键示例{“key”: “ctrlshiftc”,“command”: “composer.toggle”}### 6.3 主题和外观 Cursor完全兼容VS Code的主题系统Settings → Theme可用选项浅色/深色/系统主题自定义颜色主题文件图标主题## 七、个人配置实践 ### 7.1 我的TypeScript项目配置.cursorrulesTypeScript React项目规范语言与类型严格TypeScript无any显式返回类型标注禁止隐式anyReact规范函数组件 HooksProps接口命名XxxProps组件命名PascalCase代码风格Prettier格式化2空格缩进单引号字符串ESLint检查测试要求关键函数单元测试使用Vitest测试覆盖核心逻辑### 7.2 配置同步策略多设备配置同步方案一Git管理将.cursorrules加入版本控制在所有设备克隆同一仓库自动同步方案二云存储将配置存储在iCloud/Dropbox在Cursor中引用外部配置方案三手动同步在主设备维护配置手动复制到其他设备### 7.3 团队配置协作团队配置最佳实践在项目仓库中包含.cursorrules在README中说明团队规范Code Review时检查规则遵循定期更新规则以适应需求变化记录规则变更历史## 总结 Cursor的自定义配置系统非常强大涵盖了从代码规范到AI模型的方方面面。掌握这些配置选项可以让你的Cursor使用体验更上一层楼。 关键要点回顾 1. **.cursorrules**定义项目编码规范影响所有AI输出 2. **规则优先级**Composer临时指令 .cursorrules 全局规则 3. **模型选择**根据任务类型选择合适的模型 4. **文档集成**让AI能够查询项目特定文档 5. **终端集成**快速诊断和修复错误 下一篇文章我们将探讨Cursor的上下文管理与代码库理解这是Cursor能够提供精准AI服务的核心技术之一。 --- **相关阅读** - [04_Cursor之Composer智能体模式](./04_Cursor之Composer智能体模式.md) - [06_Cursor之上下文管理与代码库理解](./06_Cursor之上下文管理与代码库理解.md)