Node.js 20版本中CommonJS与ES模块互操作常见问题

Question

在Node.js 20中，CommonJS与ES模块互操作时常见问题之一是`require`无法直接加载ES模块。由于ES模块使用`import/export`语法并需明确文件扩展名和完整路径，当在CommonJS文件中通过`require()`引入`.mjs`或`"type": "module"`的ES模块时，会抛出错误：“Must use import to load an ES module”。此外，动态导入需改用`import()`异步语法，导致同步逻辑重构困难。同时，默认导出与命名导出在跨模块系统间易出现`default`属性错位问题，如ES模块的`export default`在CommonJS中表现为`module.exports.default`，需额外解构才能正确引用，极易引发运行时错误。

Answer 1

Node.js 20 中 CommonJS 与 ES 模块互操作的深度解析

1. 背景与模块系统演进

在 Node.js 发展历程中，CommonJS 曾是默认的模块系统，使用 require() 和 module.exports 实现同步模块加载。然而，随着 ECMAScript 模块（ESM）标准的成熟，Node.js 自 12 版本起逐步支持 ESM，并在 Node.js 20 中进一步强化其兼容性与性能。

尽管 ESM 提供了静态分析、树摇优化和更接近浏览器的标准语法，但与遗留的 CommonJS 系统共存时，产生了显著的互操作挑战，尤其是在混合项目迁移过程中。

2. 核心问题：require 无法加载 ES 模块

• 错误信息：“Must use import to load an ES module”
• 触发条件：在 .cjs 文件或未声明 "type": "commonjs" 的文件中使用 require('./module.mjs')
• 根本原因：Node.js 强制区分模块类型。若文件为 .mjs 或 package.json 中设置 "type": "module"，则被视为 ES 模块，必须通过 import 加载

这一限制源于 ESM 的异步解析机制与 CommonJS 同步执行模型的本质冲突。

3. 动态导入的异步转型挑战

场景	CommonJS 方式	ESM 对应方式
静态导入	const mod = require('./mod')	import mod from './mod.js'
动态导入	const mod = require(`./${file}`)	const mod = await import(`./${file}.js`)

由于 import() 返回 Promise，原本同步的逻辑（如配置初始化、插件注册）必须重构为异步流程，增加了架构复杂度。

4. 默认导出与命名导出的错位问题

ES 模块中使用 export default foo 时，在 CommonJS 中通过 require() 加载会得到：

{
  default: foo
}

这意味着若不进行解构，直接调用将导致运行时错误：

// ESM 文件: utils.mjs
export default function hello() { return 'Hello'; }

// CJS 文件: index.cjs
const utils = require('./utils.mjs');
utils(); // TypeError: utils is not a function

正确做法是显式解构：const { default: utils } = require('./utils.mjs');

5. 解决方案与最佳实践

1. 统一模块格式：项目初期应明确选择 ESM 或 CommonJS，避免混合使用
2. 使用 createRequire 工具：在 ESM 中安全调用 CommonJS 模块
3. 启用实验性互操作标志：Node.js 20 支持 --experimental-modules 增强兼容性
4. 构建工具辅助转换：利用 Babel、TypeScript 或 Vite 进行模块标准化输出
5. 命名导出优先：避免 default 导出以减少跨系统歧义

6. 技术实现示例：createRequire 的应用

import { createRequire } from 'module';
const require = createRequire(import.meta.url);

// 现在可以在 ESM 中安全加载 CJS 模块
const legacyModule = require('./legacy.cjs');

该方法允许 ESM 文件模拟 CommonJS 上下文，实现反向兼容。

7. 架构层面的流程设计

graph TD A[入口文件] --> B{模块类型?} B -->|ESM| C[使用 import / await import] B -->|CommonJS| D[使用 require] C --> E[处理 default 解构] D --> F[验证是否为 ESM 输出] F -->|是| G[解构 .default 属性] F -->|否| H[直接使用] G --> I[调用函数或实例化] H --> I I --> J[返回结果]

该流程图展示了在混合模块环境中安全调用的决策路径。

8. 静态分析与工具链建议

现代 IDE（如 VS Code）和 Linter（如 ESLint）可通过配置识别模块上下文：

// .eslintrc.cjs
module.exports = {
  parserOptions: {
    sourceType: 'module' // or 'script'
  }
};

结合 package.json 的 type 字段，可提升代码提示准确性，减少误用 require 的风险。