很多人建了 .cursorrules 文件，里面或者空的，或者就是复制几行"假大空"的规则。结果是：Cursor 还是改错。
核心问题：很多人不知道 .cursorrules 要定义什么，也不知道怎么验证"规则有没有用"。
这篇文章给你两样东西：
- Vue/Nuxt 项目的即用 .cursorrules 模板
- 怎么验证规则是否有效（不是靠"感觉"）
结论先说：.cursorrules = 技术栈 + 命名约定 + 禁止项清单
一个好的 .cursorrules，应该包含：
| 内容 | 为什么 | 例子 |
|---|---|---|
| 技术栈版本 | Cursor 才知道"Vue 3.5 + Pinia 2" 的弃用警告 | Vue 3.5+, Pinia 2.3, Nuxt 3.20 |
| 命名约定 | 保证生成代码风格一致 | Components: PascalCase; $files: camelCase |
| import 规则 | monorepo 和路径别名复杂，必须明确 | use @/components/xxx, not ../../../ |
| 禁止项 | 告诉 AI "千万别改这个" | Never modify store/, package.json |
| 样式系统 | 告诉它怎么写样式（CSS module / Tailwind / BEM） | Use |
| 测试 | 改完代码什么是"可接受的验收标准" | npm run test passing before commit |
实战模板 1：Vue 3 + Pinia，中等复杂度项目
# Cursor Rules for Vue 3 + Pinia Project
## 技术栈
- Runtime: Node.js 20+, npm 10+
- Frontend: Vue 3.5+, Vite 5+, Pinia 2.3+, TypeScript 5+
- Styling: Tailwind CSS 3.4+, no global CSS
- Browser: 支持 Chrome 90+, Firefox 88+, Safari 14+
## 项目结构
src/
├─ components/ (可复用 UI 组件，PascalCase)
├─ pages/ (路由页面，snake-case.vue)
├─ stores/ (Pinia store，useXxxxStore pattern)
├─ composables/ (逻辑复用，useXxxx pattern)
├─ utils/ (纯工具函数)
└─ types/ (TypeScript type 定义)
## 代码风格
### 组件命名与导出
- 组件文件：PascalCase (UserProfile.vue, ChatBox.vue)
- 导出：export default { name: 'UserProfile', ... } 或 只用 <script setup>
- Props: defineProps<{ userId: string; ... }>()
- Emits: defineEmits<{ 'update:message': [msg: string] }>()
### Import 规则（重要！）
- 从兄弟 components 导入：import Xxx from '@/components/Xxx.vue'
- 从 composables：import { useAuth } from '@/composables/useAuth'
- 从 stores：import { useAuthStore } from '@/stores/auth'
- 绝对禁止：../../../../../../foo (相对路径)
- 检查 tsconfig.json 中的 paths 配置，确保 @ 指向 src/
### 样式规则
- 使用 <style scoped module>，变量名 styles 或 $style
- Tailwind 可以用，但仅在 class 属性里（不在 style 标签里混用）
- 不要改全局 CSS（main.css, app.css）
- CSS 变量名语义化：--color-primary, --spacing-lg, NOT --var1
### 类型定义
- 定义在 src/types/ 文件，导入而不是内联
- Interface 优于 Type（除非是 utility types）
- 为 API 响应定义类型，不要用 any
- Props/Emits 用 TypeScript generics，不要用 PropTypes
### Pinia Store 规范
```ts
// stores/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
export const useUserStore = defineStore('user', () => {
const name = ref('')
const isLoggedIn = computed(() => !!name.value)
const login = (n: string) => { name.value = n }
const logout = () => { name.value = '' }
return { name, isLoggedIn, login, logout }
})
错误处理
- 不用 console.log，改用 console.error (仅异常) 或 console.warn (告警)
- API 调用必须 try/catch，错误要有 enum 类型（not string）
- Loading/Error 态在 composable 或 store 里管理，组件只负责展示
文件大小限制
- 单个 Vue 组件不超过 400 行
- 超过 400 行，拆成"container/presenter"模式
- 单个 composable 不超过 250 行
禁止清单
❌ 千万别：
- 改 package.json（不增加依赖）
- 在全局 CSS 里加样式（所有样式必须 scoped）
- 用
document.querySelector改 DOM（Vue ref 处理） - 在 store 里放 component state
- 导入循环依赖（A imports B, B imports A）
- 使用 var，只用 const/let
- 改已有组件的 Props interface（保向后兼容）
验收标准
改完代码，必须满足：
- npm run dev 启动无错误
- 页面能加载，功能可用
- console 无 error/warning
- TypeScript 类型检查通过（vue-tsc --noEmit）
- 如果改了 store，pinia devtools 里能看到状态变化
- 改了 UI，手动点一遍交互路径
---
## 实战模板 2：Nuxt 3 + 内容站（如本项目 Landing）
Cursor Rules for Nuxt 3 Landing Site
技术栈
- Runtime: Node.js 20+, pnpm 9+
- Framework: Nuxt 3.20+, Vue 3.5+, Vite 5+
- Content: @nuxt/content 2.13+, Markdown with YAML frontmatter
- 样式: Tailwind CSS 3.4+
- SEO: @nuxtjs/sitemap, @nuxtjs/robots
目录结构
pages/ (Nuxt 自动路由) components/ (可复用组件，PascalCase) content/ ├─ topics/ (文章按分类，slug.md) └─ about-html/ composables/ (useXxxx) stores/ (Pinia) public/ (静态资源) server/ ├─ api/ (.ts 自动 API 路由) └─ routes/
Markdown frontmatter 约定（内容站）
---
title: "标题"
description: "摘要，显示在搜索结果/列表里"
date: "2026-03-05" # 格式严格：YYYY-MM-DD
topic: "ai" 或 "practical-tips"
author: "作者"
tags: [tag1, tag2]
image: "/images/articles/slug-featured.jpg" # 必须存在
imageAlt: "图片描述，SEO 用"
featured: false # 首页展示用
readingTime: 10 # 分钟数
---
生成内容规范
标题与层级
- H1：文章标题（在 # frontmatter 中不再重复）
- H2：大章节（最多 5~7 个）
- H3：小节（每个 H2 下 2~4 个）
- 不跳级（不要 H1 直接跳 H3）
内外链
- 内链（同站）：使用路由路径
/topics/ai/cursor-tutorial - 外链：用
title + https://example.com的 Markdown 链接格式，打开新标签页
代码块
- 标记语言：```ts, ```vue, ```bash 等
- 一行超过 80 字符的代码，换行并缩进
表格
- 用 markdown 表格，不要 HTML table
- 表头对齐
- 行不超过 5 列（太多改成列表或拆表）
Nuxt 页面组件规范
// pages/some-page.vue
<script setup lang="ts">
import { useRoute } from 'vue-router'
useHead({
title: '标题 - HTMLPAGE',
meta: [{ name: 'description', content: '描述' }]
})
const route = useRoute()
</script>
<template>
<div class="page">
<!-- 内容 -->
</div>
</template>
<style scoped module>
.page {
/* 嵌套样式 */
}
</style>
API 调用规范（如果有 server/api/）
// server/api/some-endpoint.ts
export default defineEventHandler(async (event) => {
const body = await readBody(event)
// 验证 body
if (!body.xxx) {
throw createError({ statusCode: 400, message: '缺少 xxx' })
}
// 业务逻辑
return { success: true, data: ... }
})
禁止清单
❌ 不要：
- 改 nuxt.config.ts（除非明确指示）
- 在 Markdown 里用 HTML（用 Markdown 语法）
- 混用 useRoute 和 useRouter（明确用途）
- 在 components 里做 API 调用（用 server/api 或 composable）
---
## 怎么验证规则有效
**方法 1：对比改动前后**
在同一个任务上，试试"有规则"vs"没规则"：
- **没规则**：`git stash && rm .cursorrules && pnpm dev`，然后问 Cursor 加一个功能
- **有规则**：还原 .cursorrules，再问一遍同个功能
- **对比**：哪一次的改动更稳、更少错误？
**方法 2：看特定场景的改动**
执行这个 checklist：
| 场景 | 验证方式 | 成功标志 |
|------|---------|--------|
| 新建组件 | 问 Cursor 新建一个组件，看命名与导出 | PascalCase，用 <script setup>，没有多余的 name 字段 |
| import 路径 | 问改某个自有文件，查看 import | 都用 @/xxx，没有相对路径 |
| 样式隔离 | 问加一个样式，检查 style 标签 | 都是 <style scoped module>，没有 <style> 全局 |
| 错误处理 | 问加 API 调用，看怎么处理错误 | try/catch，error 有类型，不用 console.log |
| 禁止项 | 问改项目，看有没有改 package.json | 完全没动 package.json |
---
## 推荐工具链：让规则自动化执行
不只靠 .cursorrules，还要配合工具：
```json
{
"scripts": {
"typecheck": "vue-tsc --noEmit && nuxt prepare",
"lint": "eslint . --ext .vue,.ts,.js --fix",
"format": "prettier --write .",
"test": "vitest"
}
}
在 Cursor 的 chat 里加一条规则：
改完代码后，我会运行：
- npm run typecheck (TS 严格检查)
- npm run lint (格式与规则检查)
所以你生成的代码必须能通过这两个命令，否则说明规则没理解。
FAQ
Q：.cursorrules 文件放哪儿？
A：项目根目录。Cursor 自动扫描。如果是 monorepo，可以在 packages/*/( 下各放一份（针对不同子项目）。
Q：怎么知道规则是否被 Cursor 执行了？
A：在 Cursor 的 rules 选项卡能看到"Active rules"，如果你的 .cursorrules 在列表里，就说明被加载了。
Q：规则改了，需要重启 Cursor 吗？
A：改好保存后，新的对话会自动加载新规则。已有的对话不会更新，需要新建对话。
Q：规则太多，Cursor 会不会分散注意力？
A：会的。保持规则简练，集中在"最常踩的坑"上。比如你的项目 import 路径最容易出错，就重点强调 import 规则。
内链
- Cursor 快捷键与工作流：高效编辑
- Cursor vs GitHub Copilot vs VS Code：工具选择
- 提示词工程进阶：规则与提示词的关系
- Nuxt 最佳实践：Nuxt 项目工程化
