在node.js生态系统中，commonjs（cjs）和es modules（esm）是两种主要的模块系统。cjs采用require()和module.exports进行模块导入导出，而esm则使用import和export语法。当项目需要同时使用这两种模块类型的库时，开发者常常会遇到兼容性问题。本文将详细介绍如何在不同模块上下文（esm或cjs）中正确地混合使用这两种模块，以解决require与import共存的挑战。
理解模块类型配置
在Node.js项目中，package.json文件中的"type"字段是决定模块解析行为的关键。
- 如果"type"设置为"module"，则项目中的.js文件默认按ESM处理。
- 如果"type"设置为"commonjs"（或未设置，默认为commonjs），则项目中的.js文件默认按CJS处理。
理解这一点是解决混合模块问题的基础。
场景一：在ES Module中导入CommonJS模块
当你的package.json中设置了"type": "module"，或你的文件以.mjs结尾，表明你处于ES Module的上下文。此时，你需要导入一个CJS模块（例如prompt-sync）。
问题描述： 直接使用import { prompt } from "prompt-sync";可能会导致SyntaxError: Named export 'prompt' not found. The requested module 'prompt-sync' is a CommonJS module, which may not support all module.exports as named exports.错误。这是因为CJS模块只有一个默认导出（即module.exports的值），它不会像ESM那样提供具名导出。
解决方案： 在ESM中导入CJS模块时，CJS模块的module.exports会作为ESM的默认导出。因此，你需要使用默认导入语法。
// package.json: { "type": "module" }
import prompt from 'prompt-sync'; // 导入 prompt-sync 模块的默认导出
// 也可以显式地使用 default 关键字
// import { default as prompt } from 'prompt-sync';
const name = prompt('请输入您的名字: ');
console.log(`您好, ${name}!`);
// 如果还需要导入其他ESM模块，可以直接使用标准import
import { loadJsonFile } from 'load-json-file'; // 假设 load-json-file 是一个ESM模块
async function processJson() {
try {
const data = await loadJsonFile('config.json');
console.log('加载的JSON数据:', data);
} catch (error) {
console.error('加载JSON文件失败:', error);
}
}
processJson();解释： CJS模块（如prompt-sync）只有一个module.exports对象。当ESM导入CJS模块时，这个module.exports对象会被视为ESM的默认导出。因此，import prompt from 'prompt-sync';会把prompt-sync模块的module.exports赋值给prompt变量。
场景二：在CommonJS模块中导入ES Module
当你的package.json中未设置"type"字段（默认为commonjs），或设置为"type": "commonjs"，或你的文件以.cjs结尾，表明你处于CommonJS的上下文。此时，你需要导入一个ES Module（例如load-json-file）。
问题描述： 直接使用require("load-json-file")()可能会导致Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.错误。这是因为CJS的require()机制无法直接处理ESM。
解决方案： 在CJS模块中导入ESM时，必须使用动态import()表达式。import()是一个异步操作，它返回一个Promise，该Promise解析为一个模块对象。
// package.json: { "type": "commonjs" } 或未设置 type 字段
// 导入 CommonJS 模块 (prompt-sync)
const prompt = require('prompt-sync')();
const name = prompt('请输入您的名字: ');
console.log(`您好, ${name}!`);
// 导入 ES Module (load-json-file)
// 由于 import() 是异步的，需要在一个 async 函数中或使用 .then() 处理
async function loadAndProcessJson() {
try {
// 动态导入 ES Module
const loadJsonFileModule = await import('load-json-file');
// ES Module 的具名导出将作为导入模块对象的属性
const data = await loadJsonFileModule.loadJsonFile('config.json');
console.log('加载的JSON数据:', data);
} catch (error) {
console.error('加载JSON文件失败:', error);
}
}
loadAndProcessJson();解释：import('module-name')表达式返回一个Promise，该Promise解析为一个模块命名空间对象。这个对象包含了ESM的所有导出（包括具名导出和默认导出）。例如，如果load-json-file导出了一个名为loadJsonFile的函数，那么在动态导入后，你可以通过loadJsonFileModule.loadJsonFile来访问它。如果该ESM有默认导出，则可以通过loadJsonFileModule.default访问。
为了更简洁地访问具名导出，你也可以在await之后立即进行解构：
async function loadAndProcessJsonDestructured() {
try {
const { loadJsonFile } = await import('load-json-file');
const data = await loadJsonFile('config.json');
console.log('加载的JSON数据 (解构):', data);
} catch (error) {
console.error('加载JSON文件失败 (解构):', error);
}
}
loadAndProcessJsonDestructured();注意事项与最佳实践
- package.json的"type"字段至关重要： 明确你的主入口文件或大部分文件将运行在哪种模块上下文中。这有助于避免不必要的错误。
- 动态import()的异步性： 在CJS中导入ESM时，务必记住import()返回的是Promise。这意味着你通常需要在async函数中使用await，或者使用.then()方法来处理异步结果。
- CJS模块的默认导出： 当ESM导入CJS模块时，CJS的module.exports会成为ESM的默认导出。如果module.exports是一个函数或一个对象，你就可以直接通过默认导入来使用它。
- ESM的具名导出： 当CJS通过动态import()导入ESM时，ESM的具名导出将作为返回模块对象的属性。
- 统一模块系统： 尽管Node.js提供了互操作性机制，但从长远来看，如果可能，尽量将项目中的所有模块统一为ES Modules。这可以简化模块管理，并利用ESM的静态分析优势。对于遗留的CJS库，可以考虑寻找其ESM版本，或使用工具进行转换。
- 文件扩展名： 即使"type": "module"，你也可以使用.cjs扩展名来强制文件作为CommonJS处理。反之，即使"type": "commonjs"，你也可以使用.mjs扩展名来强制文件作为ES Module处理。这为混合项目提供了更大的灵活性。
总结
Node.js中的CommonJS和ES Modules虽然各有特点，但通过合理的配置和正确的导入语法，它们可以很好地协同工作。在ES Module环境中，通过默认导入CJS模块；在CommonJS环境中，通过动态import()导入ES Module。掌握这些策略，将帮助开发者在面对混合模块类型的项目时，能够游刃有余地构建稳定且高效的Node.js应用。
