Top Level Await是ES2022规范中新增的模块级特性，它打破了以往await只能在async函数内部使用的限制，让开发者可以在ES模块的顶层直接编写await语句，处理异步操作的逻辑变得更加直观。
Top Level Await的基本使用规则
首先需要注意，Top Level Await只能在ES模块中使用，普通的脚本文件（通过<script>标签引入且没有指定type="module"的文件）是不支持这个特性的。使用时要保证模块的顶层上下文，不需要额外的async函数包裹。
下面是一个简单的使用示例，在模块顶层直接等待一个Promise的结果：
// 定义一个返回Promise的异步函数
function fetchData() {
return new Promise((resolve) => {
setTimeout(() => {
resolve({ name: '测试数据', value: 100 });
}, 1000);
});
}
// 顶层直接使用await
const result = await fetchData();
console.log(result); // 1秒后输出 { name: '测试数据', value: 100 }
常见使用场景
1. 动态导入模块
以往动态导入模块时，需要把导入逻辑放在async函数里，使用Top Level Await可以直接在顶层完成：
// 顶层直接动态导入模块
const mathModule = await import('./mathUtils.js');
// 直接使用导入的模块方法
const sum = mathModule.add(1, 2);
console.log(sum); // 输出 3
2. 初始化模块依赖的异步资源
如果模块需要依赖一些异步获取的资源才能正常工作，比如从接口获取配置信息，使用Top Level Await可以在模块加载阶段就完成初始化：
// 获取远程配置
const config = await fetch('https://ipipp.com/api/config')
.then(res => res.json());
// 基于配置初始化模块内部变量
const apiBaseUrl = config.apiBaseUrl;
console.log('接口基础地址:', apiBaseUrl);
3. 条件性加载模块
可以根据运行时的条件来决定是否加载某个模块，不需要额外的函数包裹：
let utilsModule;
if (typeof window !== 'undefined') {
// 浏览器环境加载浏览器专用工具模块
utilsModule = await import('./browserUtils.js');
} else {
// 非浏览器环境加载Node.js专用工具模块
utilsModule = await import('./nodeUtils.js');
}
使用限制和注意事项
- 只能在ES模块中使用，普通脚本文件不支持，引入模块时需要给<script>标签添加
type="module"属性。 - 包含Top Level Await的模块会变为异步模块，它的执行会暂停在await语句处，直到Promise完成才会继续往下执行，这可能会影响其他依赖该模块的代码的执行时机。
- 不能在CommonJS模块中使用，CommonJS的
require语法和Top Level Await不兼容。 - 如果顶层的await等待的Promise被拒绝，整个模块加载过程都会失败，所以要做好错误处理，比如用
try...catch包裹await语句。
下面是一个包含错误处理的示例：
try {
const data = await fetch('https://ipipp.com/api/data')
.then(res => {
if (!res.ok) throw new Error('请求失败');
return res.json();
});
console.log('获取到的数据:', data);
} catch (err) {
console.error('数据获取失败:', err.message);
// 可以给一个默认数据
const data = { default: true };
}
兼容性说明
目前主流的现代浏览器（Chrome 89+、Firefox 89+、Safari 15+、Edge 89+）都已经支持Top Level Await，Node.js从14.8.0版本开始默认支持该特性。如果需要兼容更老的环境，可以通过Babel等转译工具将代码转换为低版本兼容的语法。
注意：如果项目中使用TypeScript，需要把target设置为ES2022或者更高版本，同时module选项也要设置为ES2022及以上，才能正确使用Top Level Await的语法。
总结
Top Level Await是ES2022中非常实用的特性，它简化了ES模块中异步操作的处理逻辑，让代码更加简洁易读。只要注意它的使用限制，在合适的场景下使用，就能有效提升开发效率。在实际开发中，遇到模块顶层需要处理异步逻辑的场景时，都可以优先考虑使用这个特性。
Top_Level_AwaitES2022JavaScript异步编程修改时间：2026-07-23 06:51:23