企业官网建设流程全解析

做 Vue3 开发这么久，我发现在<script setup>里有一个经常被忽略的细节：async 通常不能省略。这里说的不是函数声明要不要加 async，而是整个<script setup>在使用顶层 await 时，代码块本身会被隐式标记为异步，这个标记一旦缺失，组件渲染时机、数据加载顺序、甚至事件绑定都会出问题。很多刚转 Vue3 的同学第一次写后台管理系统时，都会踩到这个坑。

先说个我真实遇到的场景。上个月做后台管理系统的列表页，初始化时需要拉取用户列表和角色列表，两个接口互不依赖，我用Promise.all并行请求，很自然地写成：

<script setup> const list = ref([]) const roles = ref([]) // 忘记 async 的情况 const res = await fetch('/api/user/list') list.value = res.data </script>

结果编译不报错，但页面一片空白。原因就在于<script setup>没有显式 async 时，顶层await会导致组件被标记为 async setup，但这个标记必须配合<Suspense>才能正常工作，绕开这个约束的代价就是组件树无法挂载。这个坑从 Vue 3.2 一直到 3.5 都存在，官方文档里虽然有说明，但实际项目中踩过才会真正记住。

今天这篇就围绕这个主题，把<script setup>里 async 的使用场景、容易踩的坑、以及和 Suspense 的关系一次讲清楚，争取让大家看完就能直接套用到自己的项目里。

1. 从<script setup>的编译机制说起

1.1 script setup 本质是setup()的语法糖

Vue3 的<script setup>不是凭空出现的魔法，它最终会被编译成普通组件的setup()函数。也就是说，你在<script setup>里写的所有顶层变量、函数、计算属性，本质上都被塞进了一个函数体里，这个函数在组件创建时执行一次。

理解了这个机制，你就能明白为什么 async 在这里“通常不能省略”。普通函数里如果出现await，函数本身必须用 async 修饰，否则语法错误。<script setup>编译后也是这个逻辑——如果你在自己的代码顶层写了await，却没有让 script setup 进入异步模式，那么编译后的 setup() 函数就会变成一个包含 await 但本身不是 async 的函数，这在 JavaScript 语法层面就站不住脚。

官方设计了一个隐式规则：在<script setup>中，只要顶层出现了await表达式，该组件就会被自动标记为 async setup。听起来很智能对吧？但这个标记带来的连锁反应才是问题的关键。

1.2 async setup 改变组件加载策略

当一个组件被标记为 async setup，意味着它必须在异步依赖解决后才能渲染。Vue 的运行时并不知道这个异步依赖什么时候结束，这时候就需要一个边界组件来协调：<Suspense>。

<Suspense>的逻辑和 React 里的 Suspense 类似，当嵌套组件中存在 async setup 时，父级Suspense可以显示 fallback 内容，等待异步组件就绪后再展示正式内容。但如果你没有在组件树里提供任何<Suspense>，那这个异步组件就永远等不到“就绪”的通知，结果就是页面空白、组件不渲染，控制台可能只有一条不太明显的警告。

我见过不少团队，排查了半天最后发现是Suspense没写。这不算复杂问题，但非常隐蔽。因为编译阶段一切正常，开发服务器也不报错，只有运行时的渲染链路没有衔接上。

所以标题说“async 通常不能省略”，更准确的理解应该是：一旦你用到了顶层 await，<script setup>就必然处于异步模式，而这个异步模式必须配合<Suspense>使用，否则组件是渲染不出来的。省略了 async 的显式标记不是错误，省略了配合机制才是致命问题。

2. 哪些情况下必须使用 async setup

2.1 初始化数据依赖顶层 await

最常见的用法就是组件初始化时需要请求接口。很多人喜欢在onMounted里拉数据，但如果你希望数据在组件渲染之前就准备好，顶层 await 是最直观的写法：

<script setup> const { data: userInfo } = await getUserInfo() </script> <template> <div>{{ userInfo.name }}</div> </template>

这种写法在模板中可以安全地直接访问userInfo，因为组件在渲染前已经等待数据返回。相比onMounted里赋值 + v-if 控制渲染，代码简洁很多。代价是组件变成异步组件，父组件必须用<Suspense>包住。

有一种特殊情况：如果顶层 await 请求失败，组件会一直停留在 pending 状态，没有容错机会。所以这种用法需要配合错误处理，要么用 try/catch 包裹，要么给数据加默认值兜底，否则接口一挂页面就废了。

2.2 多个接口并行等待

后台管理系统里，表单编辑页经常需要同时拉取详情数据和字典数据。用顶层 await 加Promise.all，代码读起来非常舒服：

<script setup> const [detailRes, dictRes] = await Promise.all([ getDetail(id), getDictList() ]) const detail = ref(detailRes.data) const dictMap = ref(dictRes.data) </script>

这个写法的好处是：两个请求并发发起，总耗时约等于最慢的一个接口，而不是串行相加。而且代码是自上而下阅读的顺序，心智负担小。后面我会说，如果用onMounted+ 手动 Promise.all，代码会长一些，但能把异步逻辑从 setup 初始化剥离出来，两种方案各有利弊。

2.3 依赖异步组件的前置状态

还有一种场景不那么显眼。比如你在<script setup>里动态导入一个模块，然后用这个模块的内容初始化某个状态：

<script setup> const { ChartComponent } = await import('./components/ChartComponent.vue') const chartData = ref([]) // 后续逻辑用 ChartComponent </script>

动态 import 返回的是 Promise，所以这里也必须 await。这种场景常见于大型后台系统按需加载第三方图表库、地图组件等。如果不 await,ChartComponent就是一个 Promise 对象而不是组件定义，模板里直接用会报错或渲染不出来。

以及基于 Vue3 的 uni-app 项目、Electron 内嵌页面，逻辑都一样：只要顶层出现 await，组件就是 async setup。

2.4 async setup 对父组件的影响

需要注意的是，异步状态有传染性。子组件是 async setup，父组件不提供Suspense，整个子树都渲染不出来。如果父组件自己也是 async setup 且被爷爷组件用Suspense包裹，那问题就变成了嵌套 Suspense 的协调。

在实际项目中，我建议把顶层 await 的范围控制在叶子组件，或者用独立的布局容器包住异步区域，不要让 async setup 在整棵组件树中到处传播。否则排查问题时，你很难快速定位是哪一层异步依赖卡住了渲染。

3. 使用 Suspense 包裹 async setup

3.1 基本用法

父组件要正常渲染异步子组件，需要这样处理：

<template> <Suspense> <template #default> <AsyncChild /> </template> <template #fallback> <div>加载中...</div> </template> </Suspense> </template>

#default插槽放正常的异步组件，#fallback放加载状态。当 AsyncChild 内部的顶层 async 操作完成之前，页面会显示 fallback 内容。

这里有个容易忽略的细节：Suspense只对最近的异步依赖做等待。如果AsyncChild内部还有一个孙子组件是 async setup，那么Suspense会等待整棵子树都 resolve 后才切换掉 fallback。这是递归等待机制，不在本文深入，但要知道这个特性。

3.2 延迟组件与超时处理

Suspense 还有一个常见坑：异步过程不结束，fallback 就一直在。如果接口很慢，用户会看到长时间 loading，体验很差。Vue3.3 之后提供了timeout属性，可以用一个超时时间决定是否提前显示异常内容。但需要配合onErrorCaptured或自定义逻辑，否则只写 timeout 不处理错误，组件最终还是会卡在 pending 状态。

我建议在接口层统一加超时控制，比如 axios 的timeout配置。这样即使后端响应很慢，前端也能在指定时间后强制结束等待，避免 Suspense 无限空转。

3.3 使用 defineAsyncComponent 代替

如果你的场景只是单个异步组件（比如点击按钮才加载的大组件），不一定非要用顶层 await。defineAsyncComponent是更常用也更好控制的方案：

<script setup> import { defineAsyncComponent } from 'vue' const HeavyComponent = defineAsyncComponent(() => import('./HeavyComponent.vue') ) </script> <template> <HeavyComponent /> </template>

defineAsyncComponent是显式的异步组件，和 async setup 的区别在于：它不依赖 Suspense 也能渲染，默认有 loading、error 状态，可以配置延迟时间和超时时间。日常项目里，按需加载弹窗表单、大表格、富文本编辑器，优先用这个，而不要把<script setup>搞成 async。

这也是我想强调的一点：async setup 不是异步加载的唯一手段，甚至不是首选手段。只有当下层逻辑真的需要在初始化阶段等待数据时，才值得引入顶层 await 和 Suspense。

4. 事件处理器里省略 async 的连锁反应

4.1 事件处理与 async 函数的正确写法

前面说的是 setup 顶层，事件处理器里同样存在 async 相关的问题。比如一个提交按钮，点击后需要请求接口：

<script setup> const handleSubmit = async () => { await submitForm(data) } </script> <template> <el-button @click="handleSubmit">提交</el-button> </template>

如果你把async漏掉了，函数体内的await直接语法报错，编译器会提醒你。但有一种情况容易漏：函数体里没有肉眼可见的 await,而是调用了另一个异步函数后返回 Promise：

<script setup> // 错误示例：漏了 async function onClick() { return fetchData() } </script>

这个函数如果没有 async 修饰，返回的是 Promise 对象，Vue 事件系统拿到这个 Promise 后并不会自动处理异常。fetchData()一旦 reject，控制台会报 unhandled rejection，而且你没法在事件处理层面捕获。如果改成 async 函数，虽然同样不会自动捕获，但至少你可以用 try/catch 包裹，语义也更明确。

实际开发中，按钮提交、删除确认、弹窗关闭这类交互事件，如果涉及异步操作，我建议统一写成 async 函数，并且内部 try/catch 处理错误，不要依赖 Vue 的全局错误处理兜底。

4.2 防重复提交的经典坑

后台系统里最常见的问题：保存按钮被用户快速点了两次，导致重复提交。如果事件处理器是 async 函数，可以这样处理：

<script setup> const loading = ref(false) const handleSave = async () => { if (loading.value) return loading.value = true try { await saveData() ElMessage.success('保存成功') } finally { loading.value = false } } </script> <template> <el-button :loading="loading" @click="handleSave">保存</el-button> </template>

这段代码里 async 能不能省略？如果省略，await saveData()就报语法错误，函数永远不可能正确执行。即便你把saveData()改成不 await 而是直接链式调用，逻辑上也能跑通，但 loading 状态的管理就变得很别扭，你必须在.then()回调里关闭 loading，还要处理异常分支。

所以这里强调“async 通常不能省略”，本质上是说：在异步业务代码中，到处都依赖 await 同步化代码组织方式，而 await 必须建立在 async 函数基础上。这是 JavaScript 语言本身的规则，Vue 只是没有额外帮你解决它。

4.3 watch 和 watchEffect 中的 async 回调

另一个容易被忽略的点是 watch 回调写成 async 函数。Vue 允许这样写：

<script setup> watch(source, async (newVal, oldVal) => { await fetchData(newVal) }) </script>

这段代码能跑，但有一个坏处：watch 回调是异步的，Vue 不会 await 它的完成。如果用户在数据不断切换时，上一次请求没结束，下一次请求又发起了，就会出现竞态。解决方法是借助watchEffect的副作用清理机制：

<script setup> watchEffect(async (onCleanup) => { let cancelled = false onCleanup(() => { cancelled = true }) const res = await fetchData() if (!cancelled) { // 处理数据 } }) </script>

这里 async 也不能省略，因为await fetchData()要正常执行就必须是 async 函数。更关键的是，如果你省略了 async，onCleanup这个参数根本无法使用——它只在 async 回调被调用时注入，普通函数拿不到这个参数。这也是“省略 async 不能正常工作”的一种表现。

5. 实战案例：后台管理系统中 async 的正确使用

5.1 场景一：用户详情页数据预加载

做个用户详情页。进入页面时要拉取用户基本信息、角色列表、操作日志，三个接口互不依赖。我推荐用顶层 await + Promise.all 的方式：

<script setup> import { ref } from 'vue' import { useRoute } from 'vue-router' import { getUserInfo, getRoleList, getUserLogs } from '@/api/user' const route = useRoute() const userId = route.params.id const [userRes, roleRes, logRes] = await Promise.all([ getUserInfo(userId), getRoleList(), getUserLogs(userId) ]) const userInfo = ref(userRes.data) const roles = ref(roleRes.data) const logs = ref(logRes.data) </script> <template> <div> <h2>{{ userInfo.name }}</h2> <p>角色：{{ roles.map(r => r.name).join('、') }}</p> <ul> <li v-for="log in logs" :key="log.id">{{ log.content }}</li> </ul> </div> </template>

这样写的一个明显好处是：模板里可以直接使用userInfo、roles、logs，不需要写一堆v-if判断数据是否加载完成。但别忘了，这个组件现在是 async setup，父级路由组件必须用 Suspense 包裹：

<template> <Suspense> <template #default> <UserDetail /> </template> <template #fallback> <el-skeleton :rows="4" animated /> </template> </Suspense> </template>

5.2 场景二：异步组件加载避免阻塞渲染

详情页里有一个大的编辑弹窗，里面包含富文本编辑器。这个弹窗不是你进页面就要加载的，应该等用户点击“编辑”按钮后再动态加载。此时用defineAsyncComponent更合适：

<script setup> import { defineAsyncComponent, ref } from 'vue' const editDialogVisible = ref(false) const EditForm = defineAsyncComponent({ loader: () => import('./components/EditForm.vue'), loadingComponent: { template: '<div class="loading-tip">表单加载中...</div>' }, timeout: 5000 }) </script> <template> <el-button @click="editDialogVisible = true">编辑</el-button> <el-dialog v-model="editDialogVisible"> <EditForm v-if="editDialogVisible" :userId="userId" /> </el-dialog> </template>

这个方案中，EditForm是异步组件，但不依赖 Suspense。Vue 在首次渲染它时，会自动等待 loader 返回的 Promise，并且支持 loadingComponent 和 timeout 配置。对于弹窗、抽屉、动态表单这类场景，比把整个<script setup>搞成 async 要清晰得多。

5.3 场景三：表单回填不可省略 async

还有一个高频场景是编辑表单回填。进入编辑页后，需要用接口数据回填表单。如果你直接写：

<script setup> const form = reactive({ name: '', age: 0 }) // 错误写法 const res = await getDetail(id) Object.assign(form, res.data) </script>

这会立即触发 async setup 机制，父组件没有 Suspense 就不会渲染。正确做法之一就是上面讲的，使用顶层 await + Suspense 包裹。另一个办法是去掉顶层 await,在初始化函数里处理：

<script setup> const form = reactive({ name: '', age: 0 }) const init = async () => { const res = await getDetail(id) Object.assign(form, res.data) } init() </script>

这种写法不依赖顶级 await，组件是普通组件，不需要 Suspense。模板中可以使用v-if或v-loading控制渲染时机。优点是兼容性最好，路由使用或动态组件嵌套时不用担心异步传播；缺点是模板中访问表单字段时要小心数据未回填时的空值。

两种方式没有绝对优劣。我的项目习惯是：如果页面初始化依赖的数据接口不超过 3 个，用顶层 await + Suspense，模板更干净；如果涉及权限判断、动态路由跳转等复杂交互，用普通初始化的方式，避免 async setup 和路由守卫相互作用产生难排查的问题。

6. 从 Vue2 迁移到 Vue3 时最容易踩的 async 坑

6.1 Vue2 的 created 钩子迁移

很多从 Vue2 迁移过来的项目，在created或mounted里发请求，转到 Vue3 后有人图省事，直接在<script setup>顶层写 await。这个思路看似合理，实际上面分析过，会导致异步组件传播问题。

Vue2 时期的异步操作，核心思路是“先渲染后更新”，模板通过条件判断保证数据可用后再渲染关键字段。但 Vue3 的顶层 await 改变了这个模型，变成“先等待后渲染”。如果整个项目从 Vue2 批量迁移，可能一部分组件用顶层 await，一部分用 onMounted，两种模式混用，最后渲染时序难以预期。

我建议迁移时先审视每个组件的异步依赖颗粒度。如果是表单类页面，尽量用reactive+ 初始化函数；如果是列表类展示页，可以接受顶层 await。统一策略比纠结语法更实际。

6.2 setup() 函数中的 async 写法和 script setup 的区别

如果是用普通<script>而不是<script setup>，setup() 函数本身可以显式声明为 async：

<script> export default { async setup() { const data = await fetchData() return { data } } } </script>

这种写法在 Vue2 里没有对应概念，但 Vue3 会把它视为 async setup 组件，同样需要 Suspense。从语义上讲，async setup()其实比<script setup>顶层 await 更明确，因为它显式告诉了编译器这个 setup 是异步的。但两者最终状态一样，都需要 Suspense。

有趣的是，很多文章中提到的<script setup async>写法其实是错误的。<script setup>本身不接受 async 属性，你不能写：

<script setup async> </script>

这是不合法的，编译器会报错。正确做法是在<script setup>内部使用顶层 await,让编译器隐式推断；或者在<script>中显式写async setup()。这一点不少 Vue3 面试题会考察，答错的人挺多。

6.3 与 TypeScript 配合时的类型丢失

如果你用的是 TS，顶层 await 也会带来类型上的小麻烦。当你在<script setup lang="ts">中写了顶层 await，某些情况下模板中的类型推导会变得不够精准。因为整个组件被标记为异步后，Vue 的 template 类型检查需要多一层异步状态的推断。我实测在 Vue 3.4 + Volar 环境下，大部分场景没有问题，但如果你把顶层 await 的值传给defineProps或defineEmits，类型推导就可能失效。

尽量避免这种写法。顶层 await 的结果应该用于赋值给 ref / reactive，或者直接用于模板渲染，而不是作为 props 或 emits 的定义依据。这不是 bug，是设计边界。

7. 常见问题排查与避坑技巧合集

7.1 页面空白但控制台无错误

这是 async setup 加 Suspense 缺失的典型症状。遇到页面空白，优先检查组件树里是否有<Suspense>。可以做一个排查顺序：

1. 打开 Vue DevTools，看组件树是否渲染出目标组件。
2. 如果没有，检查目标组件的 script setup 中是否有顶层 await。
3. 如果有，回溯父组件模板，确认是否用<Suspense>包住了该组件。
4. 如果已经包了，再检查 Suspense 是否被 v-if 控制，导致组件挂载时 Suspense 不在。

第四种情况很隐蔽：<Suspense>被 v-if 包裹，异步组件在分支切换时挂载，Suspense 可能没来得及建立异步边界。这种情况建议把 Suspense 放到稳定的父级节点，不参与分支切换。

7.2 onMounted 里发请求和顶层 await 混用

我见过有人把部分请求放顶层 await，部分放 onMounted，结果模板渲染时还没拿到 onMounted 的数据，直接报 undefined 错误。这种混用会让渲染时机变得非常难推理。

建议规则：初始化数据要么全部走顶层 await，要么全部走 onMounted + ref 赋值，不要混合。走顶层 await 的优点是模板无需 v-if，缺点是必须兼容 Suspense；走 onMounted 的优点是组件是普通组件，缺点是模板要处理数据未就绪的空状态。

如果你想两者兼顾，可以在 onMounted 里用await但组件不标记为 async，因为 onMounted 是生命周期回调，函数内部 await 不会影响组件本身的同步渲染。但要记住，onMounted 里的 await 完成之前，组件已经渲染过了，模板里的 v-if 需要正确兜底。

7.3 请求失败导致 Suspense 卡死

顶层 await 没有内置错误捕获。接口 500、网络异常、超时，都会让 Promise 处于 reject 状态，而 Suspense 对这种 reject 的处理非常粗糙——它不会自动切换 fallback，也不会把错误冒泡到全局错误处理器。

解决方式是统一封装请求函数：

const request = async (url: string) => { try { const res = await fetch(url) return res.json() } catch (e) { console.error('请求失败', e) return null } }

然后顶层 await 拿到 null 时也要有兜底逻辑。实际上，对于业务后台系统，我更推荐onMounted + loading + error的状态机模式，而不是 Suspense。因为 Suspense 的 fallback 只能表达加载中，无法优雅表达加载失败的交互（重试按钮、错误提示、空数据占位）。

7.4 默认推荐方案

结合我自己的项目经验，给一个比较实用的默认方案：

• 组件初始化接口数据：优先onMounted+loading+error状态，简单直接。
• 页面核心渲染依赖某个接口且希望模板更干净的：用顶层 await + Suspense。
• 弹窗/抽屉内的大组件：用defineAsyncComponent。
• 事件处理中的异步操作：一律 async 函数，并做好 loading 和错误处理。
• 需要并行请求：Promise.all，可用在顶层 await 或 onMounted 内。

不要把<script setup>顶层 await 当成银弹。它确实能简化模板，但它把整个组件推入异步模式，这种模式在大型项目里会让渲染链路变得复杂。如果团队成员对 Suspense 不熟悉，这个方案带来的问题可能比节省的代码量更多。

8. 我的一些实际体会

做了几年 Vue3 项目，我对 async setup 最大的体会是：它不是 Vue3 的某个高级特性，而是 JavaScript 异步模型和组件渲染机制碰撞后的结果。真正理解它，必须同时理解 script setup 的编译方式、Promise 的阻塞行为、Suspense 的协调时机。

如果你在项目中遇到“页面空白”“数据加载不出来”“fallback 一直转圈”这类问题，先检查你的<script setup>里有没有顶层 await，然后顺着组件树往上看有没有 Suspense。这两步能解决 80% 的问题。

还有一个很容易被忽略的小细节：<script setup>里如果只写了 async 函数但没在顶层调用，组件并不会变成 async setup。比如你定义了一个const loadData = async () => {}，但只在按钮事件里调用它，这个组件仍然是普通组件。只有顶层“直接”使用 await 才触发异步模式。

所以在代码审查时，我会特别留意 script setup 的顶层区域。只要看到await，就要确认父组件容器是否具备 Suspense，否则直接要求改为普通初始化方式。这个审查习惯帮我们团队避免了很多线上问题。

如果你正在从 Vue2 迁移或者刚用 Vue3 写后台系统，建议先在一两个列表页尝试顶层 await + Suspense，搞清楚它的边界，再评估是否在团队中推广。技术方案没有绝对好坏，关键是匹配团队的认知水平。希望这篇文章能让你少走一些弯路。

当然，如果只是简单地省略 async 而不用 await，那不会出问题。但只要你写了 await，就请记住这个链条：await 让 script setup 成为异步组件，异步组件依赖 Suspense 才能渲染。这个链条一旦断裂，页面就会以最安静的方式失败，也是最难排查的那一种。