顶层 await 允许模块顶层直接使用 await，核心是解决初始化阶段异步依赖问题，使模块求值可暂停等待 promise 完成，从而支持基于异步结果的静态导出，同时保持 import 声明的同步性与模块图的静态可分析性。
顶层 await 允许你在模块的最外层（即非函数作用域）直接使用 await，而不需要把它包在一个 async function 里。它的核心价值不是“让写法更爽”，而是解决模块初始化阶段依赖异步资源的问题——比如从远程加载配置、连接数据库、读取环境变量或等待某个动态条件就绪。
解决模块初始化时的异步依赖问题
在没有顶层 await 之前，模块必须同步执行完毕才能被导入。如果你需要等一个 Promise 完成后再导出某些值（比如基于 API 响应决定导出哪个类），只能绕道：用 export default async function() 或把逻辑推迟到首次调用时。这导致导入方无法静态确定导出内容，破坏了 ES 模块的静态分析能力（如 tree-shaking、类型推导、构建时优化）。
- 有顶层
await后，模块会暂停执行，直到顶层await的 Promise 解决，再继续执行后续语句并完成导出 - 整个模块的加载和求值变成“异步就绪”过程，但对导入者仍是透明的：它仍通过
import同步声明依赖，只是实际完成时机延后 - 例如：config.mjs 可以
export const API_URL = await fetch('/config').then(r => r.json()).then(c => c.url)
改变模块图的执行顺序与就绪模型
ES 模块原本是“同步解析 → 同步链接 → 同步求值”的三阶段流程。顶层 await 把“求值”阶段扩展为可暂停、可等待的状态。这意味着：
- 一个含顶层
await的模块，其父模块（即import它的模块）也必须等待它完全就绪后才能完成自己的求值 - 整个模块图中，所有依赖链上的模块都会形成一个“异步就绪链”，阻塞后续模块的求值，直到该链上所有顶层
await都 resolve - 模块不会进入“错误状态”（如 rejected），而是整个导入失败；运行时会抛出未捕获的 rejection，就像同步语法错误一样中断加载
不等于让 import 变成异步操作
import 语句本身仍是静态声明、同步解析的。顶层 await 不改变模块如何被发现或解析，只影响模块**求值完成的时间点**。也就是说：
立即学习“Java免费学习笔记（深入）”；
- 你依然不能在
if或循环里动态import()然后await—— 那是动态导入的事 - 也不能在普通脚本（
）中用顶层await，除非显式声明type="module" - 它只适用于 ES 模块（.mjs 或
type="module"），CommonJS 和 IIFE 中不可用
需要注意的限制和陷阱
顶层 await 看似简单，但会引入隐式依赖和加载瓶颈：