什么是 Top-Level Await，它在 ES 模块中的使用有哪些注意事项？

Top-Level Await允许在ES模块顶层直接使用await，使模块暂停执行直至Promise完成，适用于配置加载等异步初始化场景。它会阻塞依赖模块的执行，需在.mjs文件或"type": "module"环境下使用，不可用于普通脚本。常见用途包括动态配置加载、预取远程数据和权限检查。注意事项包括可能影响启动性能、增强模块耦合、需谨慎处理错误，且一旦await失败则整个模块加载失败。例如，通过await获取配置后再导出API_URL，导入方将自动等待该异步过程完成。此功能强大但应避免滥用，以防阻塞链过长，理解其对模块加载顺序的影响至关重要。

Top-Level Await 允许你在 ES 模块的顶层作用域直接使用 await，而不需要包裹在 async 函数中。这意味着模块可以暂停自身的执行，等待一个 Promise 解析完成后再让导入它的模块继续加载。

如何工作

当一个模块使用了 Top-Level Await，它会阻塞其父模块的执行，直到 await 的 Promise 完成。这改变了模块默认立即执行的行为，适用于需要等待异步操作（如配置加载、资源初始化）完成后才能正确导出值的场景。

• 动态加载配置并基于结果导出不同实现
• 预取远程数据作为模块默认输出
• 等待权限检查或身份验证完成再暴露接口

使用注意事项

虽然 Top-Level Await 提供了便利，但使用时需注意以下几点：

蚂上有创意

支付宝推出的AI创意设计平台，专注于电商行业

64

查看详情

• 必须在 .mjs 文件或 package.json 中声明 "type": "module" 的环境下使用，仅限 ES 模块
• 会阻塞模块树中依赖该模块的所有后续导入，可能影响启动性能
• 不能在非模块脚本（如普通 script 标签）中使用
• 过度使用可能导致模块间耦合增强，降低可测试性
• 错误处理要谨慎，一旦 await 抛错，整个模块加载失败

实际示例

下面是一个合法用法：

// config.mjs
const res = await fetch('/api/config');
const config = await res.json();
export const API_URL = config.url;

// 导入这个模块的其他文件会自动等待请求完成

基本上就这些。Top-Level Await 是个强大功能，适合特定异步初始化场景，但应避免滥用以防止阻塞链过长。理解其对模块加载顺序的影响是关键。不复杂但容易忽略。

以上就是什么是 Top-Level Await，它在 ES 模块中的使用有哪些注意事项？的详细内容，更多请关注php中文网其它相关文章！