解决Node.js中CommonJS与ES模块混用挑战

Node.js生态系统长期以来主要依赖CommonJS模块系统，使用require()和module.exports进行模块导入和导出。然而，随着JavaScript语言标准引入ES模块（ESM），Node.js也开始原生支持import和export语法。这两种模块系统并存带来了灵活性，但也常常导致开发者在尝试混用不同模块类型的库时遇到兼容性错误。理解如何在两种环境中正确进行模块交互是构建健壮Node.js应用的关键。

模块系统概述

在深入解决方案之前，我们首先明确两种模块系统的基本特点：

• CommonJS (CJS)：
  • 同步加载模块。
  • 使用require()导入，module.exports或exports导出。
  • 在package.json中，默认类型为CommonJS，或者显式设置为"type": "commonjs"。
• ES Modules (ESM)：
  • 异步加载模块（尽管在Node.js中通常表现为同步加载，但其设计是异步的）。
  • 使用import导入，export导出。
  • 在package.json中，需要显式设置为"type": "module"，或者文件以.mjs结尾。

当在一个项目中同时使用CommonJS和ES模块时，开发者常常会遇到SyntaxError: Cannot use import statement outside a module、Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported或ReferenceError: require is not defined in ES module scope等错误。下面我们将分别探讨在两种主要场景下的解决方案。

在ES模块中导入CommonJS模块

当你的项目或当前文件被配置为ES模块（即package.json中设置了"type": "module"或文件为.mjs）时，你可以直接使用import语句来导入CommonJS模块。然而，需要注意的是CommonJS模块只有一个默认导出（module.exports），因此不能使用ES模块的命名导入语法。

错误示例：

// package.json: {"type": "module"}
// 尝试使用命名导入CommonJS模块
import { prompt } from "prompt-sync"; // 错误：SyntaxError: Named export 'prompt' not found.

prompt-sync是一个CommonJS模块，它通过module.exports = prompt导出了一个函数。ES模块在导入CommonJS模块时，会将CommonJS的module.exports视为其默认导出。

正确导入方式：

你需要导入CommonJS模块的默认导出。这可以通过两种等效的方式实现：

1. 直接导入默认导出：

   // package.json: {"type": "module"}
   import prompt from 'prompt-sync'; // 推荐方式
   
   const name = prompt('What is your name? ');
   console.log(`Hello, ${name}!`);

2. 使用default别名导入：

   // package.json: {"type": "module"}
   import { default as prompt } from 'prompt-sync'; // 等效于上方
   
   const name = prompt('What is your name? ');
   console.log(`Hello, ${name}!`);

这两种方式都将CommonJS模块的module.exports所导出的内容赋值给prompt变量，从而允许你在ES模块环境中正常使用该CommonJS库。

在CommonJS模块中导入ES模块

当你的项目或当前文件被配置为CommonJS模块（即package.json中未设置"type"或设置为"type": "commonjs"，或文件为.cjs）时，你不能直接使用require()来导入ES模块。Node.js会抛出Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported错误。

CoCo

智谱AI推出的首个有记忆的企业自主Agent智能体

下载

错误示例：

// package.json: {"type": "commonjs"} 或未设置type
// 尝试使用require导入ES模块
const loadJsonFile = require("load-json-file"); // 错误：ERR_REQUIRE_ESM

为了在CommonJS模块中导入ES模块，你需要使用动态import()表达式。import()函数返回一个Promise，该Promise解析为一个模块对象，其中包含了ES模块的所有导出。

正确导入方式：

由于import()返回一个Promise，你需要在async函数中使用await，或者使用.then()方法来处理Promise。

1. 使用async/await：

   这是最推荐和最现代的方式，它使异步代码看起来更像同步代码。

   // package.json: {"type": "commonjs"} 或未设置type
   
   async function processJson() {
     try {
       // 动态导入ES模块
       const loadJsonFileModule = await import('load-json-file');
   
       // 访问ES模块的命名导出
       // loadJsonFileModule是一个模块对象，其属性对应ES模块的命名导出
       const data = await loadJsonFileModule.loadJsonFile('config.json');
       console.log('Loaded JSON data:', data);
   
     } catch (error) {
       console.error('Error loading JSON:', error);
     }
   }
   
   // 调用异步函数
   processJson();
   
   // 假设你还需要一个CommonJS模块
   const prompt = require('prompt-sync')(); // CommonJS模块直接require
   const userName = prompt('Enter your name: ');
   console.log(`Hello from CJS context, ${userName}!`);

   注意事项：

   • import()表达式必须在一个async函数内部或模块的顶层（如果模块本身是ESM）使用await。在CommonJS模块的顶层直接使用await import()是不允许的，除非Node.js版本支持顶层await（这通常仅限于ES模块）。因此，将其封装在async函数中是更通用的做法。
   • 动态导入返回的是一个模块对象，你不能直接将其视为函数。你需要通过其属性来访问ES模块的命名导出（例如loadJsonFileModule.loadJsonFile）。

2. 使用.then()方法：

   如果你不想使用async/await，也可以使用Promise的.then()方法。

   // package.json: {"type": "commonjs"} 或未设置type
   
   import('load-json-file')
     .then(loadJsonFileModule => {
       // 访问ES模块的命名导出
       return loadJsonFileModule.loadJsonFile('config.json');
     })
     .then(data => {
       console.log('Loaded JSON data:', data);
     })
     .catch(error => {
       console.error('Error loading JSON:', error);
     });
   
   // 假设你还需要一个CommonJS模块
   const prompt = require('prompt-sync')();
   const userName = prompt('Enter your name: ');
   console.log(`Hello from CJS context, ${userName}!`);

总结与最佳实践

• 理解模块类型：在处理模块导入导出问题时，首先要明确当前文件和要导入的模块各自的模块类型（CommonJS还是ESM）。这通常通过package.json中的"type"字段或文件扩展名（.js, .mjs, .cjs）来确定。
• ESM导入CJS：使用import defaultExport from 'commonjs-module';或import { default as defaultExport } from 'commonjs-module';。记住CommonJS模块只有一个默认导出。
• CJS导入ESM：使用动态await import('es-module')（在async函数中）或import('es-module').then(...)。动态导入返回一个模块对象，你需要通过属性访问其导出。
• 优先统一：如果可能，尽量将项目统一到一种模块系统。对于新项目，ES模块是未来趋势，推荐使用。对于现有CommonJS项目，可以逐步迁移或使用上述兼容性方案。
• Node.js版本：确保你的Node.js版本支持你使用的ES模块特性（例如，早期版本对ESM的支持可能不完善，或者需要额外的标志）。

通过遵循这些策略，开发者可以有效地在Node.js项目中处理CommonJS和ES模块的混合使用场景，确保不同模块系统间的平稳交互。