Vue 3 Best Practices

🌟 技能核心

本技能指导开发者编写 模块化、类型安全、高性能 的 Vue 3 应用。

核心原则：

• Composition API First
• 逻辑复用 (Composables)
• 类型推导优先
• 单一数据流

---

📁 推荐项目结构

src/
├── assets/              # 静态资源
├── components/          # 通用组件
│   ├── ui/              # 基础 UI 组件
│   └── business/        # 业务组件
├── composables/         # 组合式函数 (use*.ts)
├── stores/              # Pinia stores
├── views/               # 页面组件
├── router/              # 路由配置
├── types/               # TypeScript 类型定义
├── utils/               # 工具函数
├── api/                 # API 请求封装
└── App.vue

命名规范：

类型	规范	示例
组件	PascalCase	UserProfile.vue
Composables	camelCase + use 前缀	useAuth.ts
Stores	camelCase + Store 后缀	userStore.ts
工具函数	camelCase	formatDate.ts

---

🧠 核心原则

1. Script Setup 与 Composition API

<script setup lang="ts">
// ✅ 推荐：显式导入，利于代码阅读和依赖追踪
import { ref, computed, watch, onMounted } from 'vue'
import { useUserStore } from '@/stores/userStore'

// 顶层 await 支持
const data = await fetchInitialData()

// 响应式状态
const count = ref(0)
const doubled = computed(() => count.value * 2)

// Store 使用
const userStore = useUserStore()
</script>

要点：

• 默认使用 <script setup lang="ts">，更简洁，运行时性能更好
• 支持顶层 await
• 显式导入 ref, computed, watch 等（而非依赖自动导入）

2. 响应式数据 (Reactivity)

场景	推荐	原因
基本类型	ref	清晰的 .value 访问
对象/数组（默认）	reactive	更直观；解构需 toRefs
需要整体替换/可空对象	ref	便于赋新对象与类型约束
深层嵌套大对象	reactive	仅当不解构时使用
大型外部实例	shallowRef	避免不必要的深度响应

// ✅ 推荐
const user = ref<User | null>(null)
user.value = { name: 'John' }

// ⚠️ 谨慎使用 reactive
const state = reactive({ items: [] })
// 解构会丢失响应性！
const { items } = state // ❌ items 不再是响应式

// ✅ 使用 toRefs 解构
const { items } = toRefs(state)

3. 组件通信

Props 定义（带默认值）

// Vue 3.5+ 推荐写法
const { title, count = 0 } = defineProps<{
  title: string
  count?: number
}>()

// Vue 3.4 及以下
const props = withDefaults(defineProps<{
  title: string
  count?: number
}>(), {
  count: 0
})

注意：解构式 props 需要 Vue 3.5+（或编译选项 propsDestructure: true）。否则解构结果非响应式，建议使用 withDefaults 或保留 props.xxx 访问。

Emits 定义

const emit = defineEmits<{
  change: [id: number]
  update: [value: string]
}>()

// 使用
emit('change', 123)

v-model（Vue 3.4+）

// 简化双向绑定
const modelValue = defineModel<string>()
const count = defineModel<number>('count', { default: 0 })

Slots 类型化

defineSlots<{
  default: (props: { item: Item }) => any
  header: () => any
}>()

Expose

// 暴露给父组件的方法/属性
defineExpose({
  focus: () => inputRef.value?.focus(),
  reset
})

4. 组件命名 (defineOptions)

递归组件、调试、DevTools 中必须显式命名：

defineOptions({
  name: 'TreeNode',      // 递归组件必须
  inheritAttrs: false    // 禁用属性自动透传
})

何时需要命名：

场景	必要性
递归组件	⭐ 必须
DevTools 调试	推荐
KeepAlive include/exclude	必须
Transition 组件	推荐

5. 属性透传 (inheritAttrs)

<script setup lang="ts">
defineOptions({ inheritAttrs: false })

// 获取透传的属性
const attrs = useAttrs()
</script>

<template>
  <!-- 手动绑定到内部元素 -->
  <div class="wrapper">
    <input v-bind="attrs" />
  </div>
</template>

6. 泛型组件（Vue 3.3+）

<script setup lang="ts" generic="T extends { id: number }">
defineProps<{
  items: T[]
  selected?: T
}>()

const emit = defineEmits<{
  select: [item: T]
}>()
</script>

---

🧩 逻辑复用 (Composables)

基本模式

// composables/useCounter.ts
import { ref, computed } from 'vue'

export function useCounter(initial = 0) {
  const count = ref(initial)
  const doubled = computed(() => count.value * 2)

  function increment() {
    count.value++
  }

  function reset() {
    count.value = initial
  }

  return {
    count,
    doubled,
    increment,
    reset
  }
}

带异步请求的 Composable

// composables/useFetch.ts
import { ref, shallowRef, watchEffect, toValue, type MaybeRefOrGetter } from 'vue'

export function useFetch<T>(url: MaybeRefOrGetter<string>) {
  const data = shallowRef<T | null>(null)
  const error = shallowRef<Error | null>(null)
  const loading = ref(false)

  async function execute() {
    loading.value = true
    error.value = null
    try {
      const res = await fetch(toValue(url))
      data.value = await res.json()
    } catch (e) {
      error.value = e as Error
    } finally {
      loading.value = false
    }
  }

  watchEffect(() => {
    execute()
  })

  return { data, error, loading, refresh: execute }
}

注意：MaybeRefOrGetter/toValue 需要 Vue 3.3+。低版本可用 unref 或改为仅接收 Ref。

最佳实践：

• ✅ 以 use 开头命名
• ✅ 返回对象包含响应式状态和方法
• ✅ 优先使用 VueUse 已有工具
• ❌ 不要在 Composable 中使用 this

---

📦 状态管理 (Pinia)

Setup Store（推荐）

// stores/userStore.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useUserStore = defineStore('user', () => {
  // State
  const user = ref<User | null>(null)
  const token = ref('')

  // Getters
  const isLoggedIn = computed(() => !!token.value)
  const displayName = computed(() => user.value?.name ?? 'Guest')

  // Actions
  async function login(credentials: LoginDTO) {
    const res = await api.login(credentials)
    user.value = res.user
    token.value = res.token
  }

  function logout() {
    user.value = null
    token.value = ''
  }

  return {
    user,
    token,
    isLoggedIn,
    displayName,
    login,
    logout
  }
})

要点：

• 优先使用 Setup Store，与组件写法一致
• State 保持扁平化
• Getters = computed
• Actions 处理同步/异步逻辑

---

🚫 反模式对照表

❌ 错误做法	✅ 正确做法
使用 Mixins	使用 Composables
const { prop } = props 解构	props.prop 或 toRefs(props)
在 setup 中写 created 逻辑	直接写在 setup 顶层
忘记 .value	始终在 script 中使用 .value
reactive 后解构	使用 ref 或 toRefs
Options API 混用	统一使用 Composition API

---

⚡ 性能优化

技术	场景	示例
v-memo	大型列表/表格	v-memo="[item.id, item.selected]"
shallowRef	大型外部实例	地图、图表实例
KeepAlive	缓存组件	标签页切换
路由懒加载	所有路由	() => import('./Page.vue')
defineAsyncComponent	条件渲染组件	模态框、抽屉

// 路由懒加载
const routes = [
  {
    path: '/dashboard',
    component: () => import('@/views/Dashboard.vue')
  }
]

// 异步组件
const HeavyModal = defineAsyncComponent(() => 
  import('./HeavyModal.vue')
)

---

🛠️ 技术栈推荐

分类	推荐
构建工具	Vite
路由	Vue Router 4
状态管理	Pinia
UI 组件库	Element Plus / Naive UI / Ant Design Vue
样式方案	UnoCSS / Tailwind CSS
测试	Vitest + Vue Test Utils
工具库	VueUse

---

🔄 迁移指南：Options → Composition

Options API	Composition API
data()	ref() / reactive()
computed: {}	computed()
methods: {}	普通函数
watch: {}	watch() / watchEffect()
created	<script setup> 顶层代码
mounted	onMounted()
this.xxx	直接访问变量

---

🐛 常见错误排查

问题	原因	解决
数据不更新	忘记 .value	检查 ref 访问
解构后不响应	reactive 解构	使用 toRefs()
computed 不执行	未访问 .value	确保访问响应式依赖
watch 不触发	监听了原始值	使用 getter 函数
Props 类型错误	缺少类型定义	添加泛型类型

---

📂 示例文件

本技能包含以下完整示例，位于 examples/ 目录：

文件	说明
component-example.vue	递归树形组件，展示 defineOptions 命名、插槽透传
composable-example.ts	usePagination 分页逻辑封装
store-example.ts	Pinia Setup Store 完整示例

---

🎨 常用指令示例

# 生成 Composable
/vue-coder 提取这段逻辑为一个名为 usePagination 的 Composable 函数。

# 转换 Options API
/vue-coder 将这个 Options API 组件重构为 <script setup lang="ts"> 写法。

# 优化响应式
/vue-coder 检查这段代码中 reactive 的使用是否合理，建议改为 ref。

# 添加类型
/vue-coder 为这个组件的 props 和 emits 添加完整的 TypeScript 类型。

# 性能优化
/vue-coder 分析这个列表组件的性能问题，建议优化方案。