commonjs循环引用导致模块未初始化完成就被加载，引发undefined错误；可通过console日志、require.cache分析定位闭环，用延迟加载或提取共享状态修复。
为什么 require() 一执行就卡住或报 undefined 方法
这不是语法错误，而是 CommonJS 模块加载器在解析依赖链时陷入死锁：A require B，B 又 require A，但 A 的 module.exports 还没赋值完，B 就拿到了一个空对象或部分初始化的 exports。Node.js 不会报“循环引用警告”，而是静默返回当前已导出的内容——常表现为 TypeError: xxx is not a function 或属性为 undefined。
- 典型症状：模块 A 中调用 B 的方法，却提示该方法不存在；B 中读取 A 的配置项，得到
undefined - 注意：ESM 不会出现这种“半初始化”状态，因为
import是静态声明、全量绑定，但 CommonJS 是动态执行、逐行求值 - 调试时别只看报错行——要顺着
require()调用栈往回翻，找最早出现相互require()的两个文件
如何快速定位哪两个模块在循环引用
Node.js 本身不暴露循环引用检测，但你可以靠 require.cache 和日志交叉验证。在疑似入口文件顶部加一行：
console.log('loading', module.id);
然后运行，观察输出顺序。如果看到类似 loading ./config.js → loading ./logger.js → loading ./config.js，就确认了闭环。
- 更准的方法：在每个模块开头插入
console.log(module.id, 'exports:', Object.keys(module.exports));，看哪个模块的exports在被 require 时还是空的 - VSCode 中按
Ctrl+Shift+P输入Developer: Toggle Developer Tools，在 Console 面板里搜require.cache，手动打印Object.keys(require.cache)查看已加载模块路径 - 不要依赖 IDE 的“跳转到定义”——它只看静态 import/require 字符串，无法反映实际运行时加载顺序
修复方案：延迟加载 vs 提取共享状态
不能简单删掉某个 require()，必须打破加载期依赖。两种主流解法适用场景不同：
-
延迟加载：适合工具类模块（如 logger、db client），把
require()移进函数体，让实际调用时才加载——此时对方模块早已初始化完毕function log(msg) { const config = require('./config'); console.log(config.level, msg); } -
提取共享状态：适合配置、常量、基础类型数据。新建
shared.js，只放纯数据或工厂函数，A 和 B 都 require 它，但彼此不再直接 require 对方// shared.js exports.level = 'info'; exports.getLogger = () => { ... }; - 绝对避免在模块顶层写
const x = require('./y').someFunc();——这等于把执行逻辑提前到加载阶段，极易触发死锁
VSCode 调试时断点失效或跳过 require 行
这不是断点没打上，是 Node.js 的模块缓存机制导致的：第二次 require() 直接返回缓存，根本不执行模块代码。你在 logger.js 里打的断点，第一次加载时能停，第二次从缓存取就跳过了。
- 验证方式：在
require()前加delete require.cache[require.resolve('./xxx.js')];，再运行——断点就能每次都命中（仅用于调试，勿留生产） - VSCode 的
launch.json中启用"restart": true并配合"console": "integratedTerminal"，可每次 F5 都清空缓存重载 - 真正难缠的是“伪循环”：A require B，B require C，C require A —— 这种三级闭环不会在控制台打出明显重复路径，得靠
require.cache手动展开依赖树
循环引用问题不会抛出明确错误，它藏在 undefined 和静默失败背后。最危险的是它在开发环境偶然正常（因模块加载顺序巧合），上线后因文件变更或依赖升级突然爆发。每次新增 require() 前，先问一句：这个模块会不会也被别人 require？
