node.js生态系统同时支持两种主要的模块系统：commonjs（cjs）和es模块（esm）。cjs是node.js早期采用的模块系统，使用require()和module.exports。esm是javascript官方标准，使用import和export。在实际开发中，由于历史遗留或第三方库选择，我们经常需要在一个项目中同时使用这两种模块。理解它们的互操作性对于避免常见的syntaxerror或referenceerror至关重要。
理解package.json中的"type"字段
在深入解决方案之前，首先要明确package.json文件中的"type"字段。它决定了项目中的.js文件默认被解释为CommonJS模块还是ES模块：
- 当"type": "module"时，.js文件默认被视为ES模块。
- 当"type": "commonjs"（或未指定，因为commonjs是默认值）时，.js文件默认被视为CommonJS模块。
这个设置是解决模块兼容性问题的基础。
场景一：在ES模块（"type": "module"）中引入CommonJS模块
当你的项目被配置为ES模块（package.json中设置"type": "module"），并且你需要引入一个CommonJS模块（例如prompt-sync），你会遇到SyntaxError: Named export 'prompt' not found这样的错误，如果尝试使用import { prompt } from 'prompt-sync';。这是因为CommonJS模块在被ES模块导入时，其module.exports对象会被视为ES模块的默认导出，而不是命名导出。
解决方案：使用默认导入
要正确引入CommonJS模块，你需要使用默认导入（default import）语法。CommonJS模块只有一个导出对象（即module.exports），这个对象在ESM环境中会被映射为default导出。
// package.json 设置为 "type": "module"
// 引入 CommonJS 模块 prompt-sync
// 这里的 prompt 变量将接收 prompt-sync 模块的默认导出
import prompt from 'prompt-sync';
// 或者使用具名导入语法，但指向 default
// import { default as prompt } from 'prompt-sync';
// 现在可以正常使用 prompt
const name = prompt('What is your name? ');
console.log(`Hello, ${name}!`);
// 引入 ES 模块 load-json-file (假设它是一个ES模块)
import { loadJsonFile } from 'load-json-file';
async function processJson() {
try {
const data = await loadJsonFile('config.json');
console.log('Loaded config:', data);
} catch (error) {
console.error('Error loading config:', error);
}
}
processJson();注意事项：
- CommonJS模块没有命名导出。因此，尝试从CommonJS模块中导入命名导出（如import { someNamedExport } from 'commonjs-module';）将导致运行时错误。
- 始终使用import moduleName from 'commonjs-module';或import { default as moduleName } from 'commonjs-module';来获取CommonJS模块的导出。
场景二：在CommonJS模块中（"type": "commonjs"或未指定）引入ES模块
当你的项目被配置为CommonJS模块（package.json中未指定"type"或设置为"type": "commonjs"），并且你需要引入一个ES模块（例如load-json-file），你会遇到Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported或ReferenceError: require is not defined in ES module scope等错误。这是因为require()函数无法直接加载ES模块，且ES模块环境中不识别require。
解决方案：使用动态import()
为了在CommonJS模块中引入ES模块，你需要使用动态import()表达式。动态import()返回一个Promise，该Promise解析为一个模块对象，其中包含ES模块的所有导出。
// package.json 未设置 "type" 或设置为 "type": "commonjs"
// 引入 CommonJS 模块 prompt-sync
const prompt = require('prompt-sync')();
// 声明一个异步函数来处理动态导入
async function main() {
const name = prompt('What is your name? ');
console.log(`Hello, ${name}!`);
try {
// 动态导入 ES 模块 load-json-file
const loadJsonFileModule = await import('load-json-file');
// 动态导入返回的是一个模块对象，其导出通过属性访问
const data = await loadJsonFileModule.loadJsonFile('data.json');
console.log('Loaded data:', data);
} catch (error) {
console.error('Error loading data:', error);
}
}
// 调用异步主函数
main();
// 如果不使用 async/await，也可以使用 .then()
/*
import('load-json-file')
.then(loadJsonFileModule => {
return loadJsonFileModule.loadJsonFile('another-data.json');
})
.then(data => {
console.log('Loaded another data:', data);
})
.catch(error => {
console.error('Error loading another data:', error);
});
*/注意事项：
- import()是一个异步操作，它返回一个Promise。因此，你需要在async函数中使用await，或者使用.then()方法来处理Promise的解析结果。
- 动态导入返回的是一个模块命名空间对象。你需要通过该对象的属性来访问ES模块的具名导出（例如loadJsonFileModule.loadJsonFile）。如果ES模块有默认导出，它将通过loadJsonFileModule.default访问。
- 在顶层CommonJS模块中直接使用await import()是不被允许的，除非Node.js环境支持顶层await（通常需要"type": "module"）。因此，通常需要将动态导入封装在一个async函数中。
总结与最佳实践
在Node.js项目中处理CommonJS和ES模块的混合使用，核心在于理解你的模块环境（由package.json的"type"字段决定）以及两种模块系统的导入/导出机制：
- 在ES模块中导入CommonJS： 使用默认导入（import module from 'commonjs-module';）。
- 在CommonJS模块中导入ES模块： 使用动态import()（const module = await import('es-module');），并注意其异步性。
尽管Node.js提供了这些互操作机制，但在可能的情况下，推荐统一项目的模块系统。对于新项目，优先考虑使用ES模块，因为它是JavaScript的未来标准，并提供了更好的静态分析和摇树优化能力。如果必须混用，请根据上述策略进行调整，确保代码的兼容性和可维护性。
