顶层 await 允许在 es 模块顶层直接使用 await，使模块异步化并阻塞依赖导入；支持 node.js 14.8+ 和主流浏览器，适用于配置加载、动态导入等场景，但受限于作用域、错误处理和构建工具兼容性。
ES Module 中的顶层 await 允许你在模块最外层（即非函数作用域）直接使用 await，无需包裹在 async 函数里。它从 Node.js 14.8+ 和现代浏览器（Chrome 89+、Firefox 89+、Safari 14.1+）开始被广泛支持，是加载异步资源（如配置、远程数据、动态导入）的简洁方式。
顶层 await 的基本用法
你只需在模块顶层写 await 表达式，模块会暂停执行，直到 Promise 解析完成，再继续后续代码。整个模块的执行变成异步的，且该模块对其他模块的依赖也会等待其完成。
- 只能出现在 ES Module（
.mjs文件或type="module"的 script 中），CommonJS 不支持 - 不能和
export/import混淆顺序：await可以在import之后、export之前任意位置 - 模块整体“阻塞”：其他模块
import该模块时，会等待其顶层 await 完成
常见使用场景示例
比如初始化配置、获取 API 数据、加载环境变量：
// config.mjs
const res = await fetch('/api/config');
const config = await res.json();
export const API_URL = config.apiUrl;
export const FEATURES = config.features;
又如结合动态导入做条件加载：
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
// lazy-utils.mjs
if (navigator.language.startsWith('zh')) {
const zhUtils = await import('./utils-zh.js');
export const t = zhUtils.translate;
} else {
const enUtils = await import('./utils-en.js');
export const t = enUtils.translate;
}
注意事项与限制
顶层 await 虽方便，但要注意它的行为边界：
- 不支持在循环或条件块内单独使用（语法错误），必须在模块顶层作用域
- 无法用
try/catch包裹顶层 await —— 需用await Promise.resolve().catch(...)或改用async函数封装 - 模块状态不可热更新：一旦 resolve，后续 import 始终得到相同结果（类似单例）
- 构建工具（如 Vite、Webpack 5+）支持顶层 await，但 Webpack 4 及更早版本不支持，需检查构建配置
替代方案对比
如果不支持顶层 await，常用替代方式有：
- 导出一个
async初始化函数，由使用者调用并await - 用
Promise静态属性 +export default返回 Promise，再await import() - 借助框架生命周期（如 React 的
useEffect）或应用入口处统一 await
顶层 await 让模块本身成为“异步单元”，语义更清晰，减少手动协调异步时机的负担。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
