用途
本资料是面向 Vue.js 3 应用的综合最佳实践指南，用于帮助开发者编写符合 Vue 惯用法、可维护且可扩展的代码。它包含多个类别的规则，并额外覆盖 Tailwind CSS 的 utility-first 样式集成模式与 PrimeVue 组件库的使用规范。
适用时机
资料建议在以下场景参考这些规则：编写新的 Vue 组件或 composable；使用 Composition API 实现功能；评审代码是否符合 Vue.js 模式；重构现有 Vue.js 代码；搭建组件架构；开发 Nuxt.js 应用；使用 Tailwind CSS 工具类为 Vue 组件添加样式；用 Tailwind 与 Vue 构建设计系统；原生使用 PrimeVue 组件库；通过设计令牌和 definePreset() 定制 PrimeVue 主题。
规则分类
资料按前缀划分了十类规则：Composition API（composition-）、组件设计（component-）、响应式（reactive-）、Props 与事件（props-）、模板模式（template-）、代码组织（organization-）、TypeScript（typescript-）、错误处理（error-）、Tailwind CSS（tailwind-）、PrimeVue（primevue-）。
主要能力与规则要点
Composition API：始终使用 <script setup> 编写单文件组件；原始类型用 ref()，对象用 reactive()；派生状态一律用 computed()；watch()/watchEffect() 仅用于副作用；可复用逻辑抽取为 composable；生命周期钩子放在响应式状态声明之后；Composition API 中不使用 this。
组件设计：一个组件一个职责；组件用 PascalCase、模板中用 kebab-case；组件保持在 200 行以内；必要时分离逻辑与展示；用插槽提升组合灵活性；仅通过 defineExpose() 暴露必要内容。
响应式：ref 用 const 声明；模板中由 Vue 自动解包，不写 .value；大型非响应式数据用 shallowRef()/shallowReactive()；用 readonly() 防止修改；解构 reactive 对象时用 toRefs()；复杂状态优先不可变更新。
Props 与事件：用 defineProps<T>() 定义类型；明确 required 与可选；用 withDefaults() 提供默认值；不直接修改 props；复杂校验用 validator 函数；用 defineEmits<T>() 定义事件；模板中事件名用 kebab-case；多值事件传对象。
模板：条件渲染用 v-if，频繁切换用 v-show；v-for 始终使用唯一稳定的 :key；不在同一元素上同时用 v-if 与 v-for；复杂表达式移到 computed；合理使用事件修饰符；使用 : 与 @ 简写；使用 v-model 修饰符（.trim、.number、.lazy）。
代码组织：按功能而非类型组织目录；composable 放在专用 composables/ 目录；用 index 文件做 barrel exports；保持一致命名；相关文件就近放置。
TypeScript：可复用组件用泛型；props 用 TypeScript 接口定义；显式标注 emit 载荷类型；无法推断时为 ref 指定类型；模板 ref 用 ref<InstanceType<typeof Component> | null>(null) 标注。
错误处理：用 onErrorCaptured() 实现组件错误边界；显式处理异步错误；为错误状态提供兜底 UI；合理记录错误日志。
Tailwind CSS：工具类直接写在模板中，避免自定义 CSS；类名按布局→间距→字体→视觉的顺序排列；移动优先响应式；重复的工具类模式抽取为 Vue 组件；动态类名用 computed 或辅助函数；始终使用完整类名字符串而不是拼接；交互使用状态变体（hover:、focus:、active:）；暗色模式用 dark: 前缀；在 Tailwind 配置中配置设计令牌；限制 @apply 的过度使用。
PrimeVue：按文档的 props 与 API 原生使用组件；仅通过设计令牌和 definePreset() 定制外观；绝不使用 PassThrough（pt）API 重新设置组件样式；绝不使用 unstyled 模式剥离并重建组件样式；绝不为覆盖样式而包装 PrimeVue 组件；变体使用内置 props（severity、size、outlined、rounded、raised、text）；配置 CSS layer 顺序以与 Tailwind 干净共存；利用 PrimeVue 的 TypeScript 支持；通过正确的 aria 属性维持 WCAG 合规；对大体积 PrimeVue 导入使用异步组件懒加载。
使用方式
资料以规则条目加代码示例的形式呈现，包含 <script setup> 推荐结构（导入、props/emits、composable、响应式状态、computed、watcher、方法、生命周期钩子的顺序）、composable 编写模式、带默认值的类型化 props、类型化事件、基于 defineModel 的自定义 v-model、模板 ref 类型标注、类型安全的 provide/inject、基于 onErrorCaptured 的错误边界组件、defineAsyncComponent 异步加载，以及 Tailwind 的类名排序、移动优先响应式与状态变体示例。
适用场景与限制
适用于采用 Vue.js 3 的前端项目，尤其是使用 Composition API、TypeScript、Nuxt.js，以及同时引入 Tailwind CSS 与 PrimeVue 的项目。资料中未提供具体版本兼容范围之外的收费、平台或效果数据。