Top-level await 会导致循环依赖模块图挂起，因它阻塞模块初始化完成，而模块图解析依赖各模块状态；当 A→B→A 且含 await 时，V8/Node.js 可能陷入“等待对方先完成”的死锁态，静默挂起而非报错。
Top-level await 为什么会让循环依赖模块图挂起
ESM 的 top-level await 会阻塞整个模块的初始化完成，而模块图解析阶段又依赖各模块的 [[Status]]（"evaluating" / "evaluated"）状态。当 A → B → A 形成循环，且其中任一模块含 await，V8 或 Node.js 就可能卡在“等待对方先完成初始化”的死锁态——不是报错，而是静默挂起，进程不退出、也不继续执行后续代码。
这不是语法错误，而是模块图拓扑 + 执行时序共同导致的运行时僵局。Node.js 20+ 虽有部分检测机制，但仅对简单链式循环触发 ERR_MODULE_DEPENDENCY_CIRCULAR，对含 await 的嵌套或间接循环仍可能沉默。
如何用静态分析提前暴露风险模块
不能只靠运行时观察。推荐组合使用：
- 用
node --trace-module-loading启动，观察模块加载顺序中是否出现重复进入同一模块但状态卡在loading或evaluating - 用
esbuild --bundle --format=esm --tree-shaking=true构建前扫描：它会在解析期报出Circular reference并标出含await的模块路径 - 在 VS Code 中装插件
Import Cost+ 手动检查所有含await的顶层语句是否出现在被多处 import 的工具模块里（比如auth.ts、config.ts）
重构策略：拆分 await 和导出逻辑
核心原则：让模块能同步导出符号，把异步初始化推迟到函数调用时。常见模式：
- 把
await fetch(...)移到一个命名导出函数里，如async function loadConfig()，模块顶层只做export const config = { /* stub */ }; - 用
Promise.resolve().then(() => ...)替代顶层await，但注意这仍属异步，需确保消费方显式await该 Promise - 对必须初始化即就绪的场景（如数据库连接），改用
class封装，导出实例工厂函数：export async function createDB() { const client = await connect(); return new DB(client); }
避免写 const db = await createDB() 在顶层——这又回到原问题。
Node.js 运行时可启用的兜底保护
开发期加两个 flag 可显著提升可观测性：
-
node --enable-source-maps --trace-warnings index.mjs：遇到挂起时，常伴随UnhandledPromiseRejectionWarning，此组合能定位到哪条await链没 resolve -
node --experimental-loader ./loader.mjs，自定义 loader 中拦截initialize钩子，在模块进入evaluating前记录栈和依赖路径，超时（如 5s）未完成则console.trace()
真正棘手的是跨包循环（比如 @org/utils 里用了 await，又被 @org/api 和 @org/cli 同时引用）——这种必须推动包维护者移除顶层 await，或 fork 后 patch。
