Vue 3 中 Suspense 协调异步依赖的核心是让组件可被捕获：通过 <script setup> 顶层 await 或 setup 返回 Promise，使组件变为异步；Suspense 依据 #default 插槽内组件是否满足任一条件来等待，并配合 #fallback 与 @error 处理加载与错误状态。
关键不在“怎么在 setup 里用 Suspense”，而在于：如何写出能让 Suspense 正确识别并等待的 setup 逻辑。
✅ 让 setup 支持 Suspense 的两种主流方式
-
顶层 await（最简洁）
在<script setup>中直接await一个 Promise，整个组件会自动变成异步组件，Suspense 就能捕获它：<script setup> import { ref } from 'vue' // 这个 await 会让组件进入 pending 状态 const data = await fetch('/api/user').then(r => r.json()) const name = ref(data.name) </script>⚠️ 注意：必须是顶层 await（不能包裹在函数里），且仅适用于
<script setup>；编译器会自动将该组件转为异步组件。 -
返回 Promise（兼容选项式或复杂逻辑）
若用defineComponent或需更精细控制，可在setup()中返回 Promise：export default defineComponent({ async setup() { const res = await fetch('/api/dashboard') const data = await res.json() return { data } } })Vue 会把返回 Promise 的 setup 视为异步 setup，Suspense 同样生效。
? Suspense 怎么配合这些 setup？
它只认两件事：
立即学习“前端免费学习笔记（深入）”；
-
<Suspense>的#default插槽里放的是「可能异步」的组件（比如动态导入的、含顶层 await 的、或 setup 返回 Promise 的） -
#fallback插槽放加载中 UI（比如<Spinner />或纯文字）
示例结构：
<template>
<Suspense>
<template #default>
<AsyncUserProfile />
</template>
<template #fallback>
<div class="loading">正在加载用户信息…</div>
</template>
</Suspense>
</template>其中 AsyncUserProfile.vue 只需满足上面任一条件（顶层 await 或异步 setup），Suspense 就会接管它的加载生命周期。
⚠️ 常见失效原因与修复
-
Fallback 不显示？
- 组件没真正异步（比如
await写在函数里，不是顶层） -
#default里放的是同步组件（如普通<UserCard />） - 异步操作被 try/catch 吞掉且没 rethrow，导致 Promise 立即 resolve
- 组件没真正异步（比如
多个异步一起等？
Suspense 天然聚合：只要#default下任意子组件（包括深层嵌套）有异步 setup 或顶层 await，它都会等全部完成才切换。-
错误状态没处理？
Suspense 提供@error事件，可监听异步失败：<Suspense @error="onError"> <template #default><AsyncWidget /></template> <template #fallback><Loading /></template> </Suspense>
错误不会冒泡到父组件，必须在这里捕获。
? 补充建议：和 defineAsyncComponent 搭配更可控
当异步逻辑集中在组件加载阶段（而非数据获取），推荐用 defineAsyncComponent 显式定义：
import { defineAsyncComponent } from 'vue'
const AsyncChart = defineAsyncComponent(() => import('./Chart.vue'))这样既能利用 Suspense，又能单独配置 loading 延迟、超时、错误组件等，比纯 setup 异步更易维护。
不复杂但容易忽略。
