Node.js 15.0 中使用 `Top-level await` 需要注意哪些问题？

Question

**问题：在 Node.js 15.0 中使用 Top-level await 时，模块加载行为有哪些变化和潜在陷阱？** Node.js 15.0 开始支持在模块顶层作用域中直接使用 `await`（即 Top-level await），但其会阻塞模块的加载过程，可能导致性能瓶颈或死锁风险。若依赖的 Promise 长时间未 resolve，会影响其他依赖该模块的代码执行。此外，Top-level await 只能在 ES Module（ESM）中使用，不适用于 CommonJS 模块，这可能引发兼容性问题。开发者还需注意错误处理，未捕获的异常会导致模块加载失败。如何合理使用 Top-level await 并规避这些问题？

Answer 1

一、Top-level await 的基本概念与 Node.js 15.0 引入背景

在 JavaScript 中，`await` 关键字通常只能在 `async` 函数内部使用。但随着 ECMAScript 2022（ES13）标准的推进，JavaScript 引擎开始支持 Top-level await，即允许在模块的顶层作用域中直接使用 `await`。

Node.js 自 15.0 版本起正式支持 Top-level await，前提是模块类型为 ECMAScript Module (ESM)。这一特性简化了异步初始化逻辑，使开发者能够在模块加载时等待某些异步操作完成。

二、Top-level await 对模块加载行为的影响

当一个模块中使用了 Top-level await 时，该模块的加载过程将被阻塞，直到相关的 Promise 被 resolve 或 reject。这种行为改变了传统的模块加载顺序，并引入了一些新的挑战：

• 同步化加载流程：原本并行加载的模块可能因为某个模块使用了 Top-level await 而变成串行加载。
• 依赖链阻塞：如果多个模块相互依赖，并且其中某一个模块使用了长时间未 resolve 的 await，则可能导致整个依赖链阻塞。
• 首次加载延迟：模块首次加载时需要等待所有顶层 await 完成，这可能影响应用启动性能。

// 示例：top-level await 使用方式
// config.mjs
export const data = await fetch('https://api.example.com/config').then(res => res.json());

// main.mjs
import { data } from './config.mjs';
console.log(data); // 需要等到 fetch 完成后才能执行

三、潜在陷阱与风险分析

问题类型	描述	影响范围
死锁风险	若两个模块相互依赖且都使用了 Top-level await，则可能导致循环依赖和死锁。	中高
性能瓶颈	长时间运行的 await 操作会阻塞其他代码执行，尤其是在服务端应用中影响较大。	中
错误处理缺失	未捕获的异常会导致模块加载失败，进而导致引用该模块的代码无法正常运行。	高
兼容性限制	Top-level await 只能在 ESM 中使用，CommonJS 模块不支持，容易引发模块混合使用的兼容问题。	中

四、规避策略与最佳实践

1. 避免在模块顶层进行耗时操作：尽量将耗时的异步操作封装到函数中，而非直接在顶层 await。
2. 合理组织模块依赖结构：避免循环依赖，尤其在涉及 Top-level await 时更应谨慎设计模块关系。
3. 统一模块系统：建议项目中统一使用 ESM，避免 CJS 与 ESM 混用带来的兼容性问题。
4. 加强错误处理：对 Top-level await 的 Promise 添加 catch 处理逻辑，防止模块加载失败。

// 推荐做法：封装 await 到 async 函数中
// config.mjs
let _data;
try {
  _data = await fetch('https://api.example.com/config').then(res => res.json());
} catch (err) {
  console.error('Failed to load config:', err);
  _data = {};
}
export const data = _data;

五、实际场景中的使用建议

graph TD A[模块加载开始] --> B{是否使用 Top-level await?} B -->|是| C[等待 Promise resolve] C --> D[继续加载后续模块] B -->|否| E[立即导出结果] E --> F[无需等待，快速返回]

如上图所示，Top-level await 的引入改变了模块加载的流程路径。对于关键路径上的模块，建议采用如下策略：

• 仅在必要时使用 Top-level await，例如配置文件加载、认证信息获取等。
• 对非关键数据采用懒加载或后台异步加载机制。
• 结合缓存机制减少重复网络请求。