Vue 3 的 支持顶层 await,但需 Volar 插件、tsconfig.json 配置 module: "es2022" 和 target: "es2022"、Vite ≥ 4.0 及 Vue ≥ 3.2.45。

Vue 3 的 <script setup></script> 支持顶层 await,但需满足编译和类型检查环境的双重条件,否则会报错(如 Top-level 'await' expressions are only allowed...)。这不是语法本身不支持,而是工程配置未对齐。
确保项目使用 Volar 而非 Vetur
Vetur 对 Vue 3 的 script setup + 顶层 await 支持极差,常误报 ESLint 或 TS 错误。Volar 才是官方推荐的语言支持插件。
- 在 VS Code 中禁用 Vetur(尤其当同时开发 Vue 2/3 项目时)
- 安装并启用 Volar 插件(含 Volar Server)
- 重启编辑器,确认状态栏显示 “Volar” 而非 “Vetur”
配置 tsconfig.json 支持顶层 await
TypeScript 需明确允许顶层 await,要求 module 和 target 达到最低版本标准。
-
"module": "es2022"或"esnext" -
"target": "es2017"或更高(推荐"es2022") - 建议补全
"lib": ["es2022", "dom"]避免类型缺失
示例关键配置:
{
"compilerOptions": {
"module": "es2022",
"target": "es2022",
"lib": ["es2022", "dom"],
"moduleResolution": "node",
"esModuleInterop": true,
"strict": true
}
}在 script setup 中正确使用 await
顶层 await 会自动包装为异步 setup 函数,其返回值(Promise 解析后的值)可直接用于模板或后续逻辑。
- 只能在
<script setup></script>顶层使用,不可嵌套在函数内 - 支持
await import()、await fetch()、await apiCall()等 - 响应式数据仍需用
ref/reactive显式声明
简单示例:
<script setup lang="ts">
import { ref } from 'vue'
// 顶层 await:组件初始化时等待数据加载
const userData = await fetch('/api/user').then(r => r.json())
// 响应式包装(如需后续修改)
const name = ref(userData.name)
const email = ref(userData.email)
</script><template><div>{{ name }} <small>{{ email }}</small>
</div>
</template>注意 SSR 和构建兼容性
顶层 await 在服务端渲染(如 Nuxt、Vite SSR 模式)中默认可用,但需确保构建工具版本支持:
- Vite ≥ 4.0(推荐 ≥ 5.0)
- Vue ≥ 3.2.45(含完整的编译器支持)
- 避免在非异步上下文(如
data()或普通<script></script>)中混用
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











