CommonJS循环引用导致模块未初始化完成就被加载，引发undefined错误；可通过console日志、require.cache分析定位闭环，用延迟加载或提取共享状态修复。
require()执行卡住或报undefined方法，其实是CommonJS加载死锁
这不是语法错误，也不是代码写错了，而是Node.js的CommonJS模块加载器在解析依赖链时陷入死锁：A require B，B又require A，但A的module.exports还没赋值完，B拿到的就是一个空对象或部分初始化的exports。Node.js不会报“循环引用警告”，而是静默返回当前状态——典型表现是TypeError: xxx is not a function或读取配置项得到undefined。
ESM不会出现这种问题，因为import是静态声明、全量绑定；CommonJS是动态执行、逐行求值，一旦require嵌套过深或形成闭环，就容易卡在中间状态。
- 别只看报错那一行——顺着
require()调用栈往回翻，找最早出现相互require()的两个文件 - 在每个模块顶部加
console.log('loading', module.id)，运行后观察输出顺序：如果看到loading ./a.js → loading ./b.js → loading ./a.js，就确认了闭环 - 更准的方法是在模块开头打印
console.log(module.id, 'exports:', Object.keys(module.exports))，看哪个模块被require时exports还是空的
VSCode里怎么快速定位哪两个模块在循环引用
Node.js本身不暴露循环引用检测机制，但你可以靠require.cache和日志交叉验证：
- 在疑似入口文件顶部加
console.log('loading', module.id)，然后F5调试或直接node运行，观察控制台输出顺序 - VSCode中按
Ctrl+Shift+P输入Developer: Toggle Developer Tools，在Console面板里输入Object.keys(require.cache)，手动查看已加载模块路径，找重复出现或顺序异常的路径 - 不要依赖IDE的“跳转到定义”——它只解析静态字符串，无法反映实际运行时加载顺序
修复方案选延迟加载还是提取共享状态
不能简单删掉某个require()，必须打破加载期依赖。两种解法适用场景不同：
-
延迟加载：适合工具类模块（如
logger、db client），把require()移进函数体，让实际调用时才加载——此时对方模块早已初始化完毕
例如：function log(msg) { const config = require('./config'); console.log(config.level, msg); } -
提取共享状态：适合配置、常量、基础类型数据。新建
shared.js，只放纯数据或工厂函数，A和B都require它，但彼此不再直接require对方
例如：exports.level = 'info'; exports.getLogger = () => { /* ... */ };
重构优先级：先尝试提取共享状态；如果逻辑耦合太紧，再考虑延迟加载；最彻底的是重划模块边界，把共用逻辑抽成独立模块。
npm install后仍标红？重启VSCode不是reload window就够了
VSCode不会自动重载node_modules变更后的类型定义和路径索引。你看到的波浪线，大概率是旧缓存还在起作用。
- 执行
npm install或npm update后，务必彻底退出VSCode（Windows任务栏右键→“退出”，macOS用Cmd+Q），再重开——仅“Reload Window”无效 - 如果用了
npm-check交互式更新，更新完立刻关掉所有打开的JS/TS文件，再重新打开，避免编辑器持旧引用 - 大型项目中，
node_modules/.vscode偶尔会残留错误缓存，可手动删掉（不影响依赖本身）
真正容易被忽略的是：循环依赖修复后，VSCode可能仍沿用旧的require.cache快照，不重启就看不到效果——这不是bug，是设计使然。
