如何解决Top-level await导致的模块依赖图死锁与阻塞问题

Top-level await 遇循环依赖会静默挂起而非报错，因模块卡在“evaluating”状态导致死锁；esbuild 通过 --tree-shaking=true 可提前检测并报出含 await 的循环路径。

Top-level await 本身合法，但一旦卷入循环依赖，V8 和 Node.js 就会静默挂起——不报错、不退出、也不继续执行，这是模块图解析阶段的死锁，不是语法或运行时错误。

为什么循环依赖 + top-level await 会挂起而不是报错

ESM 模块初始化有明确状态机：[[Status]] 必须从 "evaluating" 变为 "evaluated" 才算完成。而 await 会让模块卡在 "evaluating" 状态，直到 Promise settle。当 A → B → A 且其中任一模块含 await，两个模块就互相等待对方先“完成初始化”，但谁也迈不出那一步。

这种僵局不会触发 RangeError: Maximum call stack size exceeded 或 Circular dependency 报错，而是进程 CPU 归零、无日志、无响应——你只能靠 node --trace-warnings 或自定义 loader 的超时 console.trace() 捕获。

用 esbuild 预扫描识别含 await 的循环引用

构建前就能暴露问题，比 runtime 挂起好太多。esbuild 的 --tree-shaking=true 在解析期就检查模块图拓扑，遇到循环会直接报错并标出路径：

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') };

• 它只报出含 await 的那一环，不是所有循环都报，所以别以为没报就安全
• --tree-shaking=true 是关键，缺了它默认不检查循环
• 这个检查在 bundle 阶段，不适用于 dev server 场景（如 Vite/HMR），需单独加脚本验证

重构策略：把 await 移出顶层，改用函数封装

核心原则是让模块能同步导出符号，异步逻辑延迟到调用时。这不是妥协，而是恢复模块可预测性。

坏写法：

const config = await fetch('/config').then(r => r.json());<br>export { config };

好写法：

export const config = { /* stub */ };<br>export async function loadConfig() {<br>  Object.assign(config, await fetch('/config').then(r => r.json()));<br>  return config;<br>}

• 消费方必须显式调用 await loadConfig()，但至少不会拖垮整个模块图
• 如果模块被多个地方 import，loadConfig() 可加 Promise 缓存避免重复请求
• 不要用 Promise.resolve().then(() => ...) 替代顶层 await——它仍是异步，且无法被 import 语句自然等待，容易漏 await

Next.js/Vite 中启用 topLevelAwait 后仍挂起？检查 loader 时机

Webpack/Vite 的 topLevelAwait: true 只解决语法解析，不解决模块图死锁。如果你已在 next.config.js 正确配置：

webpack: (config) => {<br>  config.experiments = { ...config.experiments, topLevelAwait: true };<br>  return config;<br>}

但依然挂起，说明问题不在构建层，而在模块组织本身。

• Next.js pages 和 app 目录下的 .js 文件默认不是 ESM，需显式加 "type": "module" 到 package.json，否则 await 会被忽略或报错
• Vite 开发服务器对 await 的处理更激进，有时会提前 resolve 模块，掩盖死锁；但 build 后的产物可能暴雷，务必测试 vite build && vite preview
• Node.js 运行时若用 --loader，注意 initialize 钩子中记录模块栈的时机——必须在 evaluate 前，否则等不到挂起就结束了

最易被忽略的一点：死锁不一定发生在你写的代码里。第三方包若用了 top-level await 并参与你的依赖链（比如某个 i18n 插件内部 await import('./lang/en.js')），你也得把它当成自己的模块来排查。