NestJS 中 Node 核心模块默认导入为 undefined 但命名导入正常

• 该类导入异常的核心触发源为tsconfig.json的模块互操作配置不匹配，具体为仅开启了allowSyntheticDefaultImports但未开启esModuleInterop
  • allowSyntheticDefaultImports仅作用于IDE类型检查环节，不会修改TypeScript转译输出的运行时代码，仅保证IDE不对无默认导出模块的默认导入语法报类型错误
  • esModuleInterop是控制CommonJS模块与ES模块互操作转译逻辑的核心开关：未开启时，默认导入语法会被直接转译为require(模块名).default
  • 不同模块的运行时表现差异来源：
    • axios等多数第三方模块做了UMD兼容处理，CommonJS导出对象上自带default属性，因此require('axios').default取值正常，默认导入可正常使用
    • Node.js核心模块（path、fs等）为原生CommonJS模块，导出对象上仅挂载方法、常量等业务属性，无default键，因此require('path').default取值为undefined，触发运行时的"Cannot read property of undefined"错误
    • 命名导入的转译逻辑为const { 方法名 } = require(模块名)，不依赖esModuleInterop配置，因此始终可正常运行

• 第一步：修改项目根目录下的tsconfig.json，在compilerOptions节点下新增配置：

  "esModuleInterop": true
  

• 第二步：校验配置生效范围
  • 检查项目是否存在ts-node专属配置（如tsconfig.json内的ts-node节点、package.json中的ts-node字段），确保该配置未覆盖esModuleInterop的设置
  • 清除ts-node-dev的编译缓存后重启dev服务，避免旧缓存导致配置不生效
• 第三步（可选）：验证转译结果
  • 执行一次全量编译生成dist目录代码，查看对应模块的转译输出，若存在__importDefault辅助函数包装require返回值，说明配置已正常生效

• 开启esModuleInterop后，原有使用命名导入的代码无需修改，可完全兼容
• 尽量在项目内统一导入风格，避免无规则混用默认导入与命名导入，可减少同类CommonJS模块互操作问题

内容的提问来源于stack exchange，提问作者alexzedim