vue-composition-api-best-practices

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

版本兼容性#

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

特性最低版本参考defineOptions3.3+script-setuptoValue()3.3+script-setupdefineModel3.4+script-setupwatch 搭配 once 选项3.4+reactivityuseTemplateRef()3.5+script-setupuseId()3.5+script-setuponWatcherCleanup()3.5+reactivity

快速决策表#

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

代码组织#

• 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 步）#

text

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 选择#

text

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

Store 访问规则#

text

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

反模式 TOP 5#

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

依赖模式速查#

场景推荐模式父子组件通信Props + Emits兄弟功能交互回调参数（ onXxxChange）跨层级多对多事件总线（ useEmitt）共享状态Store 桥接组合式函数功能编排组合式函数编排模式