如何解决 Top-level await 引发的模块依赖图死锁与阻塞问题
Top-level await 语法本身是合法的，但其潜在风险在于，当它与模块的循环依赖结合时，会引发棘手的运行时问题。在 V8 引擎和 Node.js 环境中，这通常表现为进程静默挂起——没有错误提示，进程不退出，执行流程完全停滞。这并非语法或运行时错误，而是模块依赖图在解析阶段陷入了死锁状态。
循环依赖与顶层 await 为何导致静默挂起而非报错
要理解这一现象，需要从 ECMAScript 模块（ESM）的初始化机制入手。每个模块都遵循一个明确的状态机，其内部的 [[Status]] 必须从 “evaluating”（评估中）顺利过渡到 “evaluated”（评估完成），才算完成初始化。而 await 关键字的作用，正是让模块暂停在 “evaluating” 状态，直到它所等待的 Promise 被解决（resolve 或 reject）。
设想一个典型场景：模块 A 导入模块 B，模块 B 又反过来导入模块 A，形成循环依赖。如果这个环路中的任何一个模块包含了顶层 await 表达式，两个模块便会陷入“互相等待”的僵局：A 等待 B 完成初始化，B 又等待 A 完成初始化，双方都无法率先完成评估。
这种死锁不会触发常见的 RangeError: Maximum call stack size exceeded 或 Circular dependency 错误。其表现更为隐蔽：进程 CPU 使用率降至零，无任何日志输出，程序如同“冻结”。通常，开发者需要借助 node --trace-warnings 命令行参数，或在自定义加载器（loader）中设置超时并配合 console.trace() 来定位问题。
使用 esbuild 预扫描识别包含 await 的循环引用
与其在运行时遭遇难以调试的静默挂起，不如在构建阶段主动发现问题。esbuild 提供了一个实用功能：当启用 --tree-shaking=true 选项时，它会在解析阶段主动分析模块图的拓扑结构，一旦检测到包含 await 表达式的循环引用路径，便会直接报错并清晰指出问题位置。
esbuild --bundle --format=esm --tree-shaking=true src/entry.mjs
执行上述命令后，可能会看到如下输出：
× Circular reference: src/i18n/en.js → src/i18n/utils.js → src/i18n/en.js
at src/i18n/en.js:3:17 — const messages = { welcome: await loadMessage('en/welcome') };
需要注意以下几点：
- esbuild 的检查是“针对性”的，它只报告那些包含
await表达式的循环路径。这意味着，项目中若存在不包含 await 的普通循环依赖，它可能不会报错。因此，不能仅凭无报错信息就断定项目安全。 --tree-shaking=true选项是关键开关，默认的构建行为不会执行此类循环依赖检查。- 此检查发生在打包（bundle）阶段，因此对于开发服务器场景（如 Vite 的热更新 HMR）并不直接适用。在此类场景下，可能需要编写独立的验证脚本进行排查。
重构策略：将 await 移出顶层，采用函数封装
解决此类问题的核心原则是：确保模块能够同步导出其符号，而将异步逻辑延迟到被调用时才执行。这并非功能上的妥协，而是为了恢复模块初始化行为的可预测性与稳定性。
对比两种写法。典型的“问题写法”如下：
const config = await fetch('/config').then(r => r.json());
export { config };
更安全、更推荐的“优化写法”则是：
export const config = { /* 初始占位对象 */ };
export async function loadConfig() {
Object.assign(config, await fetch('/config').then(r => r.json()));
return config;
}
- 通过此方式，消费方必须显式调用
await loadConfig()才能获取配置。虽然增加了一步调用，但确保了整个模块依赖图的初始化过程不会被阻塞。 - 如果该模块被多处导入，可以在
loadConfig()函数内部实现简单的 Promise 缓存机制，避免重复发起网络请求。 - 需要警惕一种替代方案：避免使用
Promise.resolve().then(() => ...)来模拟顶层 await。它本质上仍是异步的，且无法被 import 语句自然等待，开发者容易遗漏await，从而引发更隐蔽的 Bug。
Next.js/Vite 中启用 topLevelAwait 后仍挂起？检查加载时机
许多开发者存在困惑：为何在 Webpack 或 Vite 中已配置 topLevelAwait: true，问题依然存在？这里存在一个普遍误解：这些构建工具的配置选项主要解决的是语法解析层面的问题，即允许你使用顶层 await 语法。但它们并不解决模块图死锁这一运行时逻辑问题。
假设你已在 Next.js 的 next.config.js 中做了如下正确配置：
webpack: (config) => {
config.experiments = { ...config.experiments, topLevelAwait: true };
return config;
}
如果应用仍然挂起，那么问题几乎可以确定出在模块的组织方式本身，而非构建层配置。
- 在 Next.js 中，
pages和app目录下的.js文件默认并非 ESM 模块。需确保在package.json中显式设置“type”: “module”，否则顶层的await可能被忽略或直接报错。 - Vite 开发服务器在处理
await时行为可能更“激进”，有时会提前解析（resolve）模块，这反而可能掩盖潜在的死锁问题。因此，务必使用vite build && vite preview命令对构建产物进行测试，此环境更容易暴露真实问题。 - 如果在 Node.js 运行时使用了自定义的
--loader，请特别注意其initialize钩子中记录模块调用栈的时机——它必须在模块evaluate之前完成，否则可能在挂起发生前记录流程就已结束。
最后，还有一个最易被忽略的排查方向：死锁不一定发生在你编写的代码中。如果某个第三方依赖包内部使用了顶层 await，并且它恰好位于你的模块依赖链中（例如，一个 i18n 国际化插件内部执行了 await import(‘./lang/en.js’)），那么你必须将此第三方模块纳入排查范围，将其视为项目的一部分来审视整个依赖图。
