#Vue 3 中的 setup() 执行时机与异步逻辑详解

本文详细介绍 Vue 3 组合式 API 的核心函数 setup()：它在组件生命周期中的执行时机、异步行为（await 的影响）、常见用法和最佳实践。

#一、setup() 的执行时机

setup() 是 Vue 3 组件实例创建后、渲染前执行的函数。
它相当于 Vue 2 中的 beforeCreate 和 created 的合体。

执行流程：

复制创建组件实例 → 执行 setup() → 渲染模板 → 挂载到 DOM → 执行 onMounted()

也就是说：

• 所有响应式数据（ref、reactive、computed）都在这里定义；
• 所有生命周期钩子（onMounted、onUnmounted 等）都在这里注册；
• 模板渲染会等待 setup() 执行完成（或异步返回的 Promise resolve）后再进行。

#二、setup() 的同步与异步区别

Vue 3 中 setup() 可以是：

1. 同步函数（默认）；
2. 异步函数（包含 await 或返回 Promise）。

当 setup() 是异步函数时：

• Vue 会等待 Promise resolve 后再渲染组件；
• 如果有 <Suspense> 父组件，渲染过程不会阻塞，会先显示 fallback（骨架）；
• 如果没有 <Suspense>，组件渲染会被“卡住”，直到异步结束。

#三、setup() 内部的执行顺序

复制setup() {
  // 1️⃣ 同步阶段：定义响应式数据
  const data = ref(null)

  // 2️⃣ 注册生命周期
  onMounted(() => console.log('mounted'))

  // 3️⃣ 遇到 await 会暂停 setup
  await fetchData()

  // 4️⃣ 等待结束后继续执行，最后返回给模板
}

要点说明：

• 即使在 await 之后注册 onMounted，仍然有效；
• nextTick() 在组件未挂载前调用无效，需在 onMounted 中使用；
• 若 await 抛错，未捕获则组件进入错误状态，可用 <Suspense> 的 #error 槽捕获。

#四、<script setup> 与顶层 await

在 <script setup> 中可以直接写顶层 await：

复制<script setup lang="ts">
const res = await fetch('/api/data').then(r => r.json())
</script>

<template>
  <div>{{ res.title }}</div>
</template>

• 顶层 await 会让组件的 setup 编译为异步函数；
• 行为与异步 setup() 相同；
• 建议与 <Suspense> 一起使用，否则可能导致首屏空白。

#五、不同写法对比与推荐方案

#✅ 方案 1：挂载后加载数据（不阻塞首屏）

复制<script setup>
import { ref, onMounted } from 'vue'

const list = ref([])
const loading = ref(true)

onMounted(async () => {
  const res = await fetch('/api/list').then(r => r.json())
  list.value = res
  loading.value = false
})
</script>

<template>
  <div v-if="loading">加载中...</div>
  <ul v-else>
    <li v-for="i in list" :key="i.id">{{ i.name }}</li>
  </ul>
</template>

✅ 优点：首屏加载快
⚠️ 缺点：数据稍后才出现（可配合骨架屏）

#✅ 方案 2：异步 setup + <Suspense>（有骨架占位）

父组件：

复制<template>
  <Suspense>
    <template #default>
      <UserCard />
    </template>
    <template #fallback>
      <div>加载中...</div>
    </template>
  </Suspense>
</template>

子组件：

复制<script setup>
const user = await fetch('/api/user').then(r => r.json())
</script>

<template>
  <div>{{ user.name }}</div>
</template>

✅ 优点：不白屏，支持骨架占位
⚠️ 缺点：必须使用 <Suspense>

#✅ 方案 3：SSR 预取数据（onServerPrefetch）

复制<script setup>
import { ref, onServerPrefetch } from 'vue'
const article = ref(null)

onServerPrefetch(async () => {
  article.value = await fetch('https://api/article').then(r => r.json())
})
</script>

<template>
  <div v-if="article">{{ article.title }}</div>
  <div v-else>加载中...</div>
</template>

✅ SSR 时服务端会等待数据加载完毕后渲染，客户端直接可用，避免二次请求。

#六、setup 中建议与禁忌

✅ 推荐在 setup 中做：

• 定义 ref / reactive / computed；
• 注册生命周期（onMounted、onUnmounted 等）；
• 订阅全局状态（Pinia、Vuex）；
• 初始化轻量数据；
• 服务端预取逻辑（SSR）。

❌ 不推荐在 setup 中做：

• 大量同步计算（阻塞主线程）；
• 在无 <Suspense> 的情况下直接 await；
• 直接操作 DOM（应放在 onMounted 中）。

#七、常见问题（FAQ）

Q1：在 await 之后再注册生命周期会不会失效？
不会。Vue 会等 setup 完成后再执行挂载。

Q2：异步 setup 报错怎么办？
可用 try/catch 捕获，或使用 <Suspense> 的 #error 槽。

Q3：SSR 下数据怎么预取？
使用 onServerPrefetch() 在服务端加载数据，并在客户端注水使用。

#八、最佳实践总结

#九、实战建议

• 主内容区块：<Suspense> + 顶层 await，确保内容加载完整；
• 非关键组件：使用 onMounted 拉数据，提升首屏速度；
• SSR 页面：onServerPrefetch 实现首屏即有内容；
• 性能优化：避免 setup 中的阻塞操作。

#✨ 总结

• setup() 是 Vue 3 的核心入口点；
• 异步 setup 可等待数据，但要注意阻塞风险；
• <Suspense> 能优雅地解决首屏等待问题；
• SSR 用 onServerPrefetch 实现真正的“首屏即数据”；
• 合理区分“必须首屏加载”和“可延迟加载”能显著提升性能与体验。