在node.js生态系统中，commonjs（cjs）和es modules（esm）是两种主要的模块系统。commonjs使用require()和module.exports进行模块导入导出，而es modules则采用import和export语法。由于历史原因和生态系统的演进，开发者常常需要在同一个项目中同时使用这两种模块类型的库，这便引发了模块导入的兼容性挑战。本文将深入探讨在不同项目配置下，如何有效解决commonjs与es模块的混合使用问题。
理解模块系统差异
在深入解决方案之前，理解两种模块系统的核心差异至关重要：
- CommonJS (CJS): 采用同步加载机制，主要用于Node.js环境。模块的导出通过module.exports完成，导入则通过require()函数。它不支持命名导出（named exports）的概念，所有导出都通过一个单一的module.exports对象进行。
- ES Modules (ESM): 采用异步加载机制，是JavaScript的官方模块标准，在浏览器和现代Node.js版本中均受支持。它支持命名导出（export const foo = ...）和默认导出（export default ...）。
Node.js通过package.json文件中的"type"字段来确定项目是使用ES模块（"type": "module"）还是CommonJS模块（"type": "commonjs"，或不设置，默认为CommonJS）。这个设置将决定项目内*.js文件的默认解析方式。
方案一：在ES模块环境中使用CommonJS模块
当你的package.json中设置了"type": "module"，意味着你的项目文件默认被解析为ES模块。在这种情况下，如果你需要引入一个CommonJS模块（例如prompt-sync），Node.js会将CommonJS模块的module.exports视为一个默认导出。
导入方式：
CommonJS模块没有命名导出，因此在ES模块环境中，你需要使用默认导入（default import）的方式来引入它们。
// package.json 配置: "type": "module"
// 引入 CommonJS 模块 (prompt-sync)
import prompt from 'prompt-sync';
// 或者明确指定为默认导出
// import { default as prompt } from 'prompt-sync';
// 引入 ES 模块 (load-json-file)
import { loadJsonFile } from 'load-json-file';
async function runExample() {
try {
const name = prompt('请输入你的名字: ');
console.log(`你好, ${name}!`);
const data = await loadJsonFile('data.json'); // 假设存在 data.json 文件
console.log('加载的JSON数据:', data);
} catch (error) {
console.error('发生错误:', error);
}
}
// 为了演示，创建一个简单的 data.json 文件
// { "message": "这是从data.json加载的数据" }
runExample();解释： 当ES模块导入CommonJS模块时，module.exports的值会被包裹在一个ES模块的默认导出中。因此，import prompt from 'prompt-sync';语句能够正确地将prompt-sync模块的导出（通常是一个函数或对象）赋值给prompt变量。
方案二：在CommonJS环境中使用ES模块
当你的package.json未设置"type"字段或设置为"type": "commonjs"时，你的项目文件默认被解析为CommonJS模块。在这种情况下，如果你需要引入一个ES模块（例如load-json-file），直接使用require()会导致错误，因为CommonJS不支持直接require()ES模块。
导入方式：
要从CommonJS模块中导入ES模块，你需要使用动态import()表达式。import()是一个异步操作，它返回一个Promise，该Promise解析为一个模块对象，其中包含了ES模块的所有导出。
// package.json 配置: 未设置 "type" 或 "type": "commonjs"
// 引入 CommonJS 模块 (prompt-sync)
const prompt = require('prompt-sync')();
async function runExample() {
try {
const name = prompt('请输入你的名字: ');
console.log(`你好, ${name}!`);
// 动态引入 ES 模块 (load-json-file)
const loadJsonFileModule = await import('load-json-file');
// 访问 ES 模块的命名导出
const data = await loadJsonFileModule.loadJsonFile('data.json'); // 假设存在 data.json 文件
console.log('加载的JSON数据:', data);
} catch (error) {
console.error('发生错误:', error);
}
}
// 为了演示，创建一个简单的 data.json 文件
// { "message": "这是从data.json加载的数据" }
runExample();解释：await import('load-json-file')会异步加载load-json-file这个ES模块。加载完成后，它返回一个模块对象（loadJsonFileModule），该对象的属性就是ES模块的命名导出。因此，你可以通过loadJsonFileModule.loadJsonFile来访问loadJsonFile函数。由于import()是异步的，它必须在async函数内部使用await，或者使用.then()链来处理Promise。
注意事项与最佳实践
- 统一模块系统： 对于新项目，强烈建议选择一种模块系统并坚持使用。ES Modules是JavaScript的未来标准，提供更好的静态分析和摇树优化能力。如果可能，将所有代码和依赖迁移到ESM是最佳实践。
-
package.json的"type"字段： 正确配置"type"字段至关重要。它决定了Node.js如何解析你的.js文件。
- "type": "module"：.js文件默认为ESM。
- "type": "commonjs" 或不设置：.js文件默认为CJS。
- 你也可以通过文件扩展名覆盖默认行为：.mjs文件总是ESM，.cjs文件总是CJS。
- 动态import()的异步性： 记住动态import()返回的是Promise。这意味着你不能在同步代码块中直接使用它的结果，必须配合async/await或.then()。
- 命名导出与默认导出： 在ESM中导入CJS时，CJS的module.exports被视为ESM的默认导出。在CJS中动态导入ESM时，ESM的命名导出会作为模块对象的属性。
总结
Node.js中CommonJS与ES模块的混合使用是开发过程中常见的场景。通过理解package.json中的"type"配置以及掌握在ES模块中导入CommonJS的默认导出机制，和在CommonJS中动态导入ES模块的异步import()表达式，开发者可以有效地桥接这两种模块系统。尽管存在这些兼容性方案，但为了项目的可维护性和未来发展，尽可能统一采用ES模块仍然是推荐的最佳实践。
