vue-composition-api-best-practices

Vue 3 组合式 API 与 <script setup>、TypeScript 集成及代码组织模式的最佳实践。

版本兼容性

本技能面向 Vue 3.3+，部分功能需要更高的次版本号：

特性	最低版本	参考
defineOptions	3.3+	script-setup
toValue()	3.3+	script-setup
defineModel	3.4+	script-setup
watch 搭配 once 选项	3.4+	reactivity
useTemplateRef()	3.5+	script-setup
useId()	3.5+	script-setup
onWatcherCleanup()	3.5+	reactivity

快速决策表

问题	参考阅读
我的 <script setup> 很乱，难以浏览	SFC 代码组织
某个功能的逻辑分散在很多行中	useXxx 函数模式
相同逻辑在多个组件中重复	功能提取
两个功能相互影响，但不知道正确的处理模式	跨功能依赖
Props/emits 类型安全、defineModel 使用	script setup 最佳实践
在 hooks/工具函数/插件中无法访问 Store	组件外 Store 访问
如何组织新的组合式函数文件	组合式函数设计模式
页面感觉慢，可能是响应性问题	响应性与性能
如何测试组合式函数	组合式函数测试
类型安全的 provide/inject	script setup - Provide/Inject
10+ 个功能的大型页面，全部参数注入太冗长	跨功能依赖 - 模式 6

代码组织

• SFC 代码缺乏清晰的组织结构 → 参见 sfc-code-organization
• 功能逻辑分散在脚本各处 → 参见 use-function-pattern
• 需要将可复用逻辑提取为组合式函数 → 参见 feature-extraction
• 跨功能依赖导致混乱 → 参见 cross-feature-dependencies

TypeScript 与 Script Setup

• 需要 script setup 的 TypeScript 最佳实践 → 参见 script-setup-best-practices

Store 集成

• 在 Vue 组件外部访问 Pinia store → 参见 store-without-pattern

组合式函数设计

• 设计健壮、可复用的组合式函数 → 参见 composable-design-patterns

响应性与性能

• 优化响应性以获得更好性能 → 参见 reactivity-performance

测试

• 使用 Vitest 测试组合式函数 → 参见 composable-design-patterns

---

速查表

SFC 代码组织顺序（11 步）

1. defineOptions     → 组件名称
2. defineProps       → Props 类型声明
3. defineModel       → 双向绑定（3.4+）
4. inject            → 注入依赖
5. defineEmits       → 事件类型声明
6. Store 声明         → useXxxStore()
7. 外部 hooks         → useI18n()、useDesign() 等
8. 功能声明           → const { ... } = useFeature()
9. provide           → 提供依赖
10. defineExpose     → 暴露公共 API
11. 功能实现          → function useFeature() {}

响应式 API 选择

基本类型       → ref
需要深层响应    → ref
大型对象/动态组件 → shallowRef
不需要重新赋值   → reactive（谨慎使用）
永不响应式      → markRaw + shallowRef

Store 访问规则

组件内 (<script setup>)  → useAppStore()
组件外 (hooks/utils/plugins) → useAppStoreWithOut()
解构保持响应式            → storeToRefs(store)

反模式 TOP 5

#	反模式	正确做法
1	解构 props → 丢失响应式	toRefs(props) 或直接用 props.xxx
2	组件外用 useXxxStore()	用 useXxxStoreWithOut()
3	ref 用于动态组件/大对象	用 shallowRef
4	混用 Options API + script setup	只选一种风格
5	事件监听不清理	onUnmounted 中移除 / 使用 VueUse 的 useEventListener

依赖模式速查

场景	推荐模式
父子组件通信	Props + Emits
兄弟功能交互	回调参数（onXxxChange）
跨层级多对多	事件总线（useEmitt）
共享状态	Store 桥接组合式函数
功能编排	组合式函数编排模式
大型页面多功能编排	混合策略（核心链显式 + 叶子闭包）