Vue 3 组合式 API 实战：setup 语法糖的最佳实践

学完这篇，你能把 Vue 3 的 `<script setup>` 从“能跑”写到“团队里别人也愿意看”，包括 props/emits 的正确声明、逻辑抽成 composables、副作用清理和一套固定的代码排列顺序。

第一步：先把 setup() 函数换成 `<script setup>`

如果你还在写这种老写法：

<script>
import { ref } from 'vue'
export default {
  setup() {
    const count = ref(0)
    return { count }
  }
}
</script>

改成语法糖，少写一堆样板：

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

`<script setup>` 里的顶层变量、函数、import 进来的组件，模板里直接就能用，不需要 return，也没有 `this`。

注意：`defineProps`、`defineEmits`、`defineExpose`、`defineModel` 是编译宏，不用 import，也不能写在 `if`、`function` 里面——它们必须在顶层。

第二步：props、emits、v-model 全部显式声明

这是最容易被新手忽略的一步：不声明就收不到，也不会有类型提示。用 TypeScript 时推荐类型式声明：

<script setup lang="ts">
const props = withDefaults(
  defineProps<{ title: string; count?: number }>(),
  { count: 0 }
)

const emit = defineEmits<{
  (e: 'change', value: number): void
  (e: 'close'): void
}>()

// Vue 3.4+ 才稳定可用，替代 props + emit('update:xxx')
const keyword = defineModel<string>({ default: '' })
</script>

`defineModel` 让 `v-model="keyword"` 双向绑定变成一行搞定，父组件写法不变。

注意：不要解构 props 直接用，比如 `const { count } = defineProps(...)`，在 Vue 3.5 之前会丢掉响应式。要么 `props.count`，要么 `const { count } = toRefs(props)`。用 `reactive` 声明对象同理，整体替换对象时响应式会断，所以状态统一用 `ref` + `.value` 更省心。

第三步：把能复用的逻辑抽成 composables

组合式 API 真正的价值在这一步。约定俗成：文件名和函数名都以 `use` 开头，放 `src/composables/` 目录，返回 ref 和函数。

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

export function useCounter(initial = 0) {
  const count = ref(initial)
  const double = computed(() => count.value * 2)
  function inc(step = 1) {
    count.value += step
  }
  return { count, double, inc }
}

组件里一行接入：

<script setup>
import { useCounter } from '@/composables/useCounter'
const { count, double, inc } = useCounter(10)
</script>

判断标准很简单：这段逻辑换个页面还能用，就该抽出去；只服务当前页面的，留在组件里别硬抽。

第四步：生命周期和副作用，谁注册谁清理

<script setup>
import { onMounted, onUnmounted, watch } from 'vue'

function onResize() { /* ... */ }

onMounted(() => {
  window.addEventListener('resize', onResize)
})

onUnmounted(() => {
  window.removeEventListener('resize', onResize)
})

const props = defineProps({ id: String })
const controller = { current: null }

watch(() => props.id, async (id) => {
  controller.current?.abort()
  controller.current = new AbortController()
  const res = await fetch(`/api/detail/${id}`, { signal: controller.current.signal })
  // ...
}, { immediate: true })
</script>

要点：`watch` 有明确来源用 `watch`；需要自动追踪依赖、又不需要旧值时才用 `watchEffect`。请求类副作用记得用 `AbortController` 或标志位取消，避免快速切页时旧响应覆盖新数据。

注意：定时器（`setInterval`）、事件监听、WebSocket、第三方图表实例，都必须在 `onUnmounted` 里销毁。这是 Vue 3 内存泄漏的第一大来源，`<script setup>` 不会帮你自动回收。

第五步：需要给父组件用的，用 defineExpose 明说

`<script setup>` 默认是封闭的，父组件通过 ref 拿不到里面任何东西，必须显式暴露：

<script setup>
import { ref } from 'vue'
const inputRef = ref(null)
function focus() { inputRef.value?.focus() }
defineExpose({ focus })
</script>

父组件：`const formRef = ref(null)`，模板上 `ref="formRef"`，然后 `formRef.value.focus()`。

第六步：固定一套书写顺序，减少 review 争吵

在团队里推行这个排列，谁看都顺：

1. import 语句
2. `defineProps` / `defineEmits` / `defineModel`
3. `ref` / `reactive` 状态
4. `computed`
5. `watch` / `watchEffect`
6. 普通方法
7. 生命周期钩子
8. `defineExpose`

另外两个小习惯：单文件超过 300 行就该拆子组件；不要把 `computed` 写成能改的“假状态”，需要写回就用 `get`/`set` 双函数。

小结

• `<script setup>` 顶层即模板作用域，无 `this`、无 `return`；编译宏必须写在顶层。
• props/emits/v-model 一律显式声明并用类型标注，别解构 props 丢响应式。
• 可复用逻辑抽成 `useXxx` composables，状态统一用 `ref` + `.value`。
• `onMounted` 里注册的副作用，`onUnmounted` 里必须清干净。
• 子组件能力要 `defineExpose` 才对外可见。
• 用固定的代码排列顺序，比争论风格更有效。