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')），你也得把它当成自己的模块来排查。
