Vue 3 / Nuxt 3 最佳实践

技能文档

---
name: diegosouzapw-vuejs-best-practices
title: Vue 3 / Nuxt 3 最佳实践
description: Vue 3 与 Nuxt 3 性能优化与最佳实践指南，含 10 大类 50+ 条按影响程度排序的规则，覆盖响应式优化、包体积、服务端性能、组件设计、Composition API、Pinia 状态管理、渲染性能与 TypeScript 集成。当用户编写、审查或重构 Vue/Nuxt 代码，或需要优化性能、包体积、加载速度时使用。触发词：Vue 最佳实践、Nuxt 性能优化、Composition API、Pinia、组件设计、响应式优化、包体积优化。
category: 开发工具
---

# Vue.js 最佳实践

面向 Vue 3 与 Nuxt 3 应用的性能优化指南，含 10 大类 50+ 条规则，按影响程度排序，可指导自动化重构与代码生成。

## 适用时机

- 编写新的 Vue 3 组件或 Nuxt 3 页面
- 使用 Composition API 与组合式函数（composables）
- 实现数据获取（客户端或服务端）
- 使用 Pinia 管理状态
- 审查代码的性能问题
- 重构既有 Vue/Nuxt 代码
- 优化包体积或加载速度

## 技能工作流

规则按优先级分为 10 类，审查/编写代码时按下表顺序逐类应用：

| 优先级 | 类别 | 影响 | 前缀 |
|-------|------|------|------|
| 1 | 响应式优化 | 严重 | `reactivity-` |
| 2 | 包体积优化 | 严重 | `bundle-` |
| 3 | Nuxt 3 服务端性能 | 高 | `nuxt-` |
| 4 | 组件设计模式 | 高 | `component-` |
| 5 | Composition API 模式 | 中高 | `composable-` |
| 6 | 状态管理（Pinia） | 中高 | `pinia-` |
| 7 | 渲染性能 | 中 | `rendering-` |
| 8 | TypeScript 集成 | 中 | `typescript-` |
| 9 | 测试模式 | 中低 | `testing-` |
| 10 | 高级模式 | 低 | `advanced-` |

## 快速参考

### 1. 响应式优化（严重）

- `reactivity-shallowref` - 大对象无需深层响应式时使用 shallowRef
- `reactivity-shallowreactive` - 扁平对象使用 shallowReactive
- `reactivity-computed-cache` - 昂贵计算用 computed（自动缓存）
- `reactivity-toraw` - 传给外部库时使用 toRaw()
- `reactivity-markraw` - 非响应式对象（类实例、第三方实例）用 markRaw()
- `reactivity-effectscope` - 用 effectScope() 批量清理副作用

### 2. 包体积优化（严重）

- `bundle-tree-shaking` - 从 'vue' 导入，不要从内部包（@vue/reactivity、@vue/runtime-core）导入
- `bundle-async-components` - 重组件用 defineAsyncComponent
- `bundle-dynamic-imports` - 路由级代码分割用动态 import()
- `bundle-icon-imports` - 图标直接导入，避免图标库的桶文件（barrel files）
- `bundle-lodash-es` - 使用 lodash-es 并按需导入
- `bundle-analyze` - 用 rollup-plugin-visualizer 定位体积膨胀
- `bundle-external-cdn` - 适时将大依赖外置到 CDN

### 3. Nuxt 3 服务端性能（高）

- `nuxt-usefetch` - SSR 友好的数据获取用 useFetch/useAsyncData
- `nuxt-lazy-components` - 组件加 Lazy 前缀实现自动懒加载
- `nuxt-payload-reduce` - 用 pick/transform 选项减小载荷
- `nuxt-cache-route` - 用 routeRules 配置缓存策略
- `nuxt-server-components` - 仅服务端组件用 .server.vue
- `nuxt-prerender` - 静态页面在构建时预渲染
- `nuxt-islands` - 局部水合用 Nuxt Islands
- `nuxt-nitro-cache` - API 路由利用 Nitro 缓存

### 4. 组件设计模式（高）

- `component-sfc-setup` - 始终使用 `<script setup>` 语法
- `component-props-destructure` - defineProps 使用解构以保持响应式
- `component-emits-typed` - 始终用 TypeScript 定义 emits
- `component-slots-typed` - 用 defineSlots 为插槽标注类型
- `component-expose` - defineExpose 慎用，优先 props/emits
- `component-v-once` - 静态内容用 v-once
- `component-v-memo` - 列表项优化用 v-memo
- `component-teleport` - 弹窗/浮层用 Teleport

### 5. Composition API 模式（中高）

- `composable-naming` - 组合式函数以 use 开头（useAuth、useFetch）
- `composable-return-object` - 返回对象而非数组，提升使用体验
- `composable-cleanup` - 在 onUnmounted 中处理清理
- `composable-async` - 正确处理异步状态（loading、error、data）
- `composable-ssr-safe` - 浏览器专属代码检查 `import.meta.client`
- `composable-provide-inject` - provide/inject 配合 InjectionKey 保证类型安全
- `composable-vueuse` - 自写组合式函数前优先用 VueUse

### 6. 状态管理 Pinia（中高）

- `pinia-setup-syntax` - 优先使用 setup store 写法
- `pinia-storetorefs` - 用 storeToRefs() 保持响应式
- `pinia-actions-async` - 异步操作放 actions，不放 getters
- `pinia-persist` - 持久化用 pinia-plugin-persistedstate
- `pinia-reset` - 实现 $reset 用于 store 清理
- `pinia-subscribe` - 副作用用 $subscribe
- `pinia-ssr-hydration` - Nuxt 中正确处理 SSR 水合

### 7. 渲染性能（中）

- `rendering-v-show-v-if` - 频繁切换用 v-show，低频条件用 v-if
- `rendering-key-attribute` - v-for 始终用唯一 :key（避免用索引作 key）
- `rendering-virtual-scroll` - 长列表（100+ 项）用虚拟滚动
- `rendering-keep-alive` - 用 KeepAlive 缓存组件实例
- `rendering-suspense` - 异步组件加载状态用 Suspense

### 8. TypeScript 集成（中）

- `typescript-props-interface` - props 用 interface 定义而非 type
- `typescript-ref-type` - 显式标注 ref 类型：`ref<string>('')`
- `typescript-template-ref` - 模板引用标注类型：`ref<HTMLInputElement | null>(null)`
- `typescript-component-type` - 组件引用用 `ComponentPublicInstance`
- `typescript-generic-components` - 可复用模式用泛型组件
- `typescript-strict-inject` - 类型安全的 provide/inject 用 InjectionKey<T>
- `typescript-event-handlers` - 事件处理器正确标注类型

### 9. 测试模式（中低）

- `testing-vitest` - 单元测试用 Vitest（Vue 生态原生）
- `testing-vue-test-utils` - 组件测试用 @vue/test-utils
- `testing-composables` - 组合式函数隔离测试
- `testing-pinia` - store 测试用 createTestingPinia
- `testing-msw` - API 模拟用 MSW
- `testing-playwright` - Nuxt 的 E2E 用 Playwright

### 10. 高级模式（低）

- `advanced-render-function` - 动态组件生成用渲染函数
- `advanced-custom-directive` - DOM 操作封装为自定义指令
- `advanced-plugin-pattern` - 插件按规范的 install 函数结构组织

## 决策树

### ref 还是 reactive

```
什么类型的数据？
│
├── 基础类型（string、number、boolean）
│   └── ref() ✓
│
├── 对象/数组（需要深层响应式）
│   └── reactive() ✓
│
├── 大对象（性能敏感）
│   └── shallowRef() 或 shallowReactive() ✓
│
└── 非响应式数据（类实例、外部库）
    └── markRaw() ✓
```

### useFetch 还是 $fetch（Nuxt）

```
代码运行在哪里？
│
├── 组件/页面（需要 SSR + 响应式）
│   └── useFetch() 或 useAsyncData() ✓
│
├── 服务端 API 路由
│   └── $fetch() ✓
│
├── 事件处理器（仅客户端）
│   └── $fetch() ✓
│
└── 组合式函数（可复用）
    └── 带key 的 useFetch() ✓
```

### 组件通信模式

```
组件间是什么关系？
│
├── 父 → 子
│   └── Props ✓
│
├── 子 → 父
│   └── Emits ✓
│
├── 兄弟组件
│   └── Pinia store 或 provide/inject ✓
│
├── 深层嵌套（props 层层透传）
│   └── provide/inject ✓
│
└── 全局状态
    └── Pinia store ✓
```

## 反模式清单

### ❌ 不要：

- 在新 Vue 3 项目中使用 Options API
- 直接修改 props
- 在 `<script setup>` 中使用 `this`
- 用 reactive() 包装基础类型
- 同一元素同时使用 v-if 和 v-for
- v-for 循环遗漏 :key
- 动态列表用索引作 :key
- 在脚本中访问 ref 不加 .value
- 无必要地嵌套 Pinia store
- 在组件中使用 `$fetch`（应使用 useFetch）

### ✅ 要：

- 使用 Composition API 配合 `<script setup>`
- 用 TypeScript 定义 props 和 emits
- 派生状态用 computed
- 副作用用 watchEffect
- 善用 VueUse 组合式函数
- 全局状态用 Pinia
- 处理 loading/error 状态
- 在 onUnmounted 中清理副作用
- 异步组件配合 Suspense

## 性能检查清单

上线前核对：

- [ ] **包体积分析过吗？** 无意外的大依赖
- [ ] **懒加载？** 路由与重组件已做代码分割
- [ ] **响应式优化？** 该用 shallowRef 的地方用了
- [ ] **SSR 正常？** 无水合不匹配
- [ ] **图片优化？** 使用 nuxt/image 或类似方案
- [ ] **API 请求去重？** useFetch 配置了正确的 key
- [ ] **状态管理高效？** store 中无过度请求
- [ ] **列表渲染优化？** 长列表启用虚拟滚动

使用说明

# Vue 3 / Nuxt 3 最佳实践

10 大类 50+ 条按影响排序的性能优化规则，覆盖响应式、包体积、SSR、组件设计、Pinia、渲染与 TypeScript。

## 使用示例

1. 写新组件前对 Agent 说：「按 Vue 最佳实践帮我写这个列表组件，注意渲染性能」
2. 代码审查时说：「用 Vue 性能规则审查这段代码，按优先级列出问题」
3. 参照文末「性能检查清单」做上线前核对

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。