最佳 Cursor Rules：优质 .cursorrules 资源汇总 (2026)

最佳 Cursor 规则：优秀 .cursorrules 集合 (2026)

Cursor 的 .cursorrules 文件是 AI 辅助开发中被低估的核心功能之一。通过在项目根目录放置 .cursorrules 文件，您可以为 Cursor 的 AI 提供一组持久的指令，从而塑造其生成代码的方式。合适的规则可以显著提高代码质量、强制执行团队规范并减少反复修改。

本指南精选了针对流行框架、语言和项目类型的最佳 .cursorrules 配置。每套规则都经过社区贡献和实际应用场景的不断优化。

.cursorrules 的工作原理

当您在项目根目录创建 .cursorrules 文件时，Cursor 会自动将其内容作为该项目中每次 AI 交互的系统上下文的一部分。这意味着：

• Tab 补全 遵循您的规范
• 聊天响应 使用您偏好的模式
• 代码生成 匹配您的技术栈和风格
• 重构建议 符合您的架构设计

文件位置

your-project/
  .cursorrules    <-- 放置在此处
  src/
  package.json
  ...

截至 2026 年，Cursor 还支持更细粒度规则管理的 .cursor/rules 目录格式，但根目录下的 .cursorrules 文件仍被广泛使用且受到完全支持。

编写规则的一般最佳实践

在深入研究特定模板之前，以下是使规则更有效的原则：

原则	示例
明确技术栈	"使用 Next.js 15 App Router，不要使用 Pages Router"
定义命名规范	"变量使用 camelCase，组件使用 PascalCase"
指定文件结构	"API 路由放在 app/api/，组件放在 components/"
设定错误处理模式	"始终使用 try/catch 并配合类型化错误"
包含否定指令	"在 TypeScript 中禁止使用 any 类型"
保持在 2000 tokens 以内	过长的规则会稀释重要的指令

Next.js / React (TypeScript)

这是最受欢迎的规则集之一。它涵盖了使用 TypeScript、Tailwind CSS 和现代 React 模式的 Next.js App Router。

你是一位 TypeScript、React、Next.js App Router 和 Tailwind CSS 专家。

核心原则：
- 编写简洁、类型安全的 TypeScript 代码，并提供准确的示例。
- 使用函数式和声明式编程模式。避免使用类（Classes）。
- 优先选择迭代和模块化，而非代码重复。
- 使用带有助动词的描述性变量名（如 isLoading, hasError）。
- 目录使用小写加连字符（例如 components/auth-wizard）。
- 优先使用具名导出（named exports）而非默认导出（default exports）。

Next.js 规范：
- 默认使用带有 Server Components 的 App Router。
- 将特定页面的组件与页面放在同一目录下。
- 使用路由分组（圆括号）进行布局组织。
- 为每个路由段实现 loading.tsx 和 error.tsx。
- 表单提交和数据变更使用 Server Actions。
- 优先使用 Next.js Image 组件而非 img 标签。
- 使用 next/font 加载字体。

TypeScript：
- 对象形状优先使用 interface 而非 type。
- 避免使用 enums。使用带有 as const 的对象常量。
- 使用严格模式。严禁使用 any 或 @ts-ignore。
- 为所有函数定义返回类型。
- 使用 Zod 进行运行时验证。

样式：
- 仅使用 Tailwind CSS。不使用内联样式或 CSS Modules。
- 使用 cn() 工具函数（clsx + tailwind-merge）处理条件类。
- 遵循移动优先的响应式设计。
- 使用 globals.css 中定义的 CSS 变量作为主题颜色。

组件：
- 使用 shadcn/ui 作为组件库。
- 创建小巧、专注的组件（50 行以下）。
- 公用组件存放在 components/ 目录。
- 页面专用组件放在其页面文件旁边。

数据获取：
- 尽可能在 Server Components 中获取数据。
- 对于数据密集型页面使用 React Server Components。
- 实现完善的 Error Boundaries 和 Loading 状态。
- 客户端数据获取使用 SWR 或 TanStack Query。

Python (FastAPI)

针对向 FastAPI 构建 API 优化的规则：

你是一位 Python、FastAPI 和可扩展 API 开发专家。

核心原则：
- 编写简洁、技术化的 Python 代码，并带有准确的类型提示。
- 在适当处使用函数式编程。避免不必要的类。
- 优先选择迭代和模块化，而非重复代码。
- 使用描述性变量名（is_active, has_permission）。
- 遵循 PEP 8 风格指南。

FastAPI 规范：
- 所有请求和响应模型均使用 Pydantic v2。
- 使用 Depends() 实现依赖注入。
- 为所有路由处理器使用 async def。
- 使用 APIRouter 将路由组织到不同的 router 文件中。
- 错误响应使用带有正确状态码的 HTTPException。
- 使用 Pydantic 实现完善的请求验证。
- 使用 lifespan 上下文管理器管理启动/关闭事件。

项目结构：
- app/main.py - FastAPI 应用初始化
- app/routers/ - 按领域分组的路由处理器
- app/models/ - SQLAlchemy 或 Pydantic 模型
- app/schemas/ - 请求/响应 Pydantic 模型
- app/services/ - 业务逻辑
- app/dependencies/ - 共享依赖
- app/core/ - 配置、安全、数据库设置

错误处理：
- 为领域错误创建自定义异常类。
- 使用中间件进行全局错误处理。
- 始终返回一致的错误响应模型。
- 使用 structlog 或 loguru 记录错误。

数据库：
- 使用带有异步会话的 SQLAlchemy 2.0。
- 使用 Alembic 进行数据库迁移。
- 严禁在路由处理器中编写原始 SQL。
- 使用 Repository 模式进行数据访问。

测试：
- 使用 pytest 和 pytest-asyncio 编写测试。
- 使用 httpx.AsyncClient 进行 API 测试。
- 在测试中模拟外部服务。
- 目标代码覆盖率 80% 以上。

Go (后端服务)

针对 Go 后端服务的规则：

你是一位 Go、微服务架构和后端开发专家。

核心原则：
- 编写遵循 Effective Go 指南的地道 Go 代码。
- 优先考虑简洁性和可读性，而非奇技淫巧。
- 显式处理所有错误。严禁使用 _ 丢弃错误。
- 使用有意义的变量名。短名称仅用于有限范围。
- 保持函数简短并专注于单一职责。

规范：
- 在寻求第三方库之前，尽可能使用标准库。
- ID/O 操作函数的第一个参数使用 context.Context。
- 在使用接口的地方定义接口，而不是在实现的地方。
- 使用表格驱动测试（Table-driven tests）。
- 返回错误，不要使用 panic。
- 使用结构体嵌入（struct embedding）进行组合。

项目结构：
- cmd/ - 应用程序入口点
- internal/ - 私有应用程序代码
- pkg/ - 公共库代码（如适用）
- api/ - API 定义 (OpenAPI, protobuf)
- migrations/ - 数据库迁移文件

错误处理：
- 使用 fmt.Errorf("context: %w", err) 包装错误。
- 为预期的错误条件定义 Sentinel 错误。
- 使用 errors.Is() 和 errors.As() 进行错误检查。
- 严禁同时记录日志并返回错误。二选其一。

并发：
- 使用带有正确同步机制的 goroutines。
- 始终使用 contexts 处理取消操作。
- 使用 channels 进行通信，使用 mutexes 管理状态。
- 避免 goroutine 泄漏 - 确保每个 goroutine 都有退出路径。

Rust

针对 Rust 项目的规则：

你是一位 Rust、系统编程和安全并发代码专家。

核心原则：
- 编写利用类型系统和所有权模型的地道 Rust 代码。
- 优先选择编译时保证而非运行时检查。
- 使用描述性名称。除众所周知的缩写（ctx, tx, rx）外，避免使用缩写。
- 函数保持在 40 行以内。为复杂逻辑提取辅助函数。
- 为所有公共条目编写文档注释。

规范：
- 为所有可能失败的操作使用 Result<T, E>。生产代码中严禁使用 unwrap()。
- 函数参数优先使用 &str 而非 String。
- 库错误类型使用 thiserror，应用错误类型使用 anyhow。
- 在适当处派生常用 Trait：Debug, Clone, PartialEq。
- 使用开启了 pedantic lints 的 clippy。
- 使用 rustfmt 格式化所有代码。

项目结构：
- src/lib.rs - 库根目录
- src/main.rs - 二进制入口点
- src/models/ - 数据结构
- src/handlers/ - 请求处理器
- src/services/ - 业务逻辑
- tests/ - 集成测试

错误处理：
- 为每个模块定义自定义错误类型。
- 使用 ? 运算符进行错误传播。
- 转换错误时提供上下文。
- 在模块边界将外部错误映射为特定领域的错误。

异步：
- 使用 tokio 作为异步运行时。
- 优先使用 async 函数而非手动实现 Future。
- 使用 tokio::select! 进行并发操作。
- 网络操作务必设置超时。

Swift (iOS)

针对使用 SwiftUI 的 iOS 开发规则：

你是一位 Swift、SwiftUI 和 iOS 应用开发专家。

核心原则：
- 编写遵循 Apple API 设计指南的整洁、地道的 Swift 代码。
- 默认优先使用值类型（structs, enums）而非引用类型（classes）。
- 优先选择组合而非继承。
- 使用有意义的名称。避免缩写。
- 保持 View 小巧且专注。

SwiftUI 规范：
- View 本地状态使用 @State，子视图使用 @Binding。
- 对于 iOS 17+，使用 @Observable（Observation 框架）代替 ObservableObject。
- 将可重用 View 提取到单独的文件中。
- 使用 ViewModifiers 进行共享样式设置。
- 长列表优先使用 LazyVStack/LazyHStack。
- View 中的异步工作使用 .task {}。

架构：
- 在 SwiftUI 中遵循 MVVM 模式。
- 将业务逻辑放在 ViewModels 中，而不是 Views 中。
- 所有异步操作使用 Swift Concurrency (async/await)。
- 使用协议（Protocols）定义依赖项以增强可测试性。
- 通过 Environment 进行依赖注入。

数据：
- 使用 SwiftData 进行本地持久化 (iOS 17+)。
- 将模型定义为具有正确关联关系的 @Model 类。
- 为迁移配置 ModelContainer。

错误处理：
- 尽可能使用类型化 throws (Swift 6+)。
- 使用本地化描述向用户展示错误。
- 对可能失败的操作使用 Result 类型。

Tailwind CSS / UI 设计

专门针对前端样式的规则：

你是一位使用 Tailwind CSS 的响应式 UI 设计专家。

核心原则：
- 仅使用 Tailwind CSS 工具类。除非绝对必要，否则不使用自定义 CSS。
- 遵循移动优先的响应式设计 (sm:, md:, lg:, xl:)。
- 确保符合 WCAG 2.1 AA 可访问性标准。
- 使用语义化 HTML 元素 (nav, main, section, article)。
- 使用 Tailwind 的间距缩放保持间距的一致性。

样式模式：
- 使用 cn() 辅助函数 (clsx + tailwind-merge) 处理条件类。
- 对相关的 utility 进行分组：布局、间距、字体、颜色、效果。
- 谨慎使用 @apply，且仅在组件级样式表中使用。
- flex/grid 布局优先使用 gap 而非 margin。
- 最大宽度内容使用 container mx-auto。

响应式设计：
- 先设计移动端布局，再添加断点修饰符。
- 页面布局使用 grid，组件布局使用 flex。
- 在 320px, 768px, 1024px, 和 1440px 断点进行测试。
- 需要时使用 clamp() 实现流体字体。

深色模式：
- 使用 dark: 变体支持深色模式。
- 为随主题变化的颜色使用 CSS 变量。
- 测试两种主题的对比度。

可访问性：
- 为所有图像添加 alt 文本。
- 使用正确的标题层级 (h1 到 h6)。
- 确保焦点指示器可见。
- 在语义化 HTML 不足的地方使用 aria 属性。
- 保持正文文本 4.5:1 的对比度。

创建您自己的规则

这是一个构建您自己的 .cursorrules 的模板：

你是一位 [技术栈] 专家。

核心原则：
- [代码风格偏好]
- [命名规范]
- [错误处理方式]

项目结构：
- [目录布局]

规范：
- [框架特定规则]
- [测试方法]
- [状态管理]

禁止操作：
- [需要避免的反模式]
- [弃用的方法]

有效规则的技巧

建议做	避免做
明确版本号	说 "使用现代实践"
提供具体示例	编写模糊的指南
包含负面限制	只编写正面规则
随项目演进更新规则	设定后便置之不理
保持在 2000 tokens 以内	编写完整的风格指南
专注于 AI 容易出错的地方	重复 AI 已经做得很好的地方

总结

精心编写的 .cursorrules 文件能将 Cursor 从通用的 AI 助手转变为深谙团队规范的背景感知型编码伙伴。从上方模板中选择一个开始，根据您的项目进行自定义，并随着您发现 AI 需要指导的地方不断迭代。

如果您正在构建 AI 驱动的应用程序，并需要可靠的图像生成、视频创建或其他媒体任务 API，请查看 Hypereal AI。Hypereal 提供的开发者友好型 API，可与本指南中涵盖的现代技术栈无缝协作。