顶层 await 是 ES2025 正式标准，允许在 ESM 模块顶层直接使用 await，使模块变为异步模块并按序等待 Promise 完成，仅适用于模块环境，不可用于脚本或 CommonJS。
顶层 await 是指在 ECMAScript 模块（ESM）的最外层作用域（即模块顶层）直接使用 await 表达式，而无需将其包裹在 async 函数中。它自 ES2025（第13版）起成为正式标准，让模块可以“等待”异步操作完成后再完成自身求值，从而简化依赖异步初始化的场景。
顶层 await 的核心特性
它只在模块顶层有效，且会使该模块变成一个“异步模块”。一旦模块中出现顶层 await，整个模块的执行会被暂停，直到所有顶层 await 的 Promise 都 fulfilled。其他导入该模块的代码也会等待其完全就绪后才继续执行。
- 不能在脚本（
非模块）或 CommonJS 中使用 - 模块加载器会将含顶层 await 的模块视为
async module，其import返回的是 Promise - 多个顶层
await会按顺序执行（串行），但可配合Promise.all()并行发起
如何在模块中使用顶层 await
只需把 await 写在模块最外层即可，常用于初始化配置、获取远程数据、等待资源加载等。
例如：
// config.mjs
const response = await fetch('/api/config');
const config = await response.json();
export { config };
另一个常见用法是并行加载多个资源：
// data.mjs
const [usersRes, postsRes] = await Promise.all([
fetch('/api/users'),
fetch('/api/posts')
]);
export const users = await usersRes.json();
export const posts = await postsRes.json();
使用时需要注意的限制
顶层 await 不是万能的，有明确的边界和约束：
- 无法在函数、条件语句、循环内部使用（那些地方本来就支持
await，但必须在async函数里） - 不能与
var声明混用（因提升机制冲突），推荐统一用const或let - 动态
import()可与顶层 await 结合，实现按需异步加载子模块 - Node.js 需启用 ESM（如文件扩展名为
.mjs或"type": "module"），浏览器需通过加载
对模块依赖链的影响
如果模
块 A 顶层 await 了某 Promise，而模块 B 导入 A，那么 B 的执行会自动等待 A 就绪。这种“隐式等待”简化了异步初始化流程，但也要求开发者清楚模块加载时序——比如不能在顶层试图读取尚未 resolve 的导出值。
例如，下面写法是安全的：
// main.mjs
import { config } from './config.mjs';
console.log(config); // ✅ 此时 config 已确定存在且已解析完成
但如果错误地在非模块环境或未正确声明类型的地方使用，会直接报语法错误：await is only valid in async functions and the top level bodies of modules。
