Node.js中CommonJS与ES模块混合使用的策略与实践

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。

腾讯混元

腾讯混元大由腾讯研发的大语言模型，具备强大的中文创作能力、逻辑推理能力，以及可靠的任务执行能力。

65

查看详情

解决方案：使用动态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"字段决定）以及两种模块系统的导入/导出机制：

1. 在ES模块中导入CommonJS： 使用默认导入（import module from 'commonjs-module';）。
2. 在CommonJS模块中导入ES模块： 使用动态import()（const module = await import('es-module');），并注意其异步性。

尽管Node.js提供了这些互操作机制，但在可能的情况下，推荐统一项目的模块系统。对于新项目，优先考虑使用ES模块，因为它是JavaScript的未来标准，并提供了更好的静态分析和摇树优化能力。如果必须混用，请根据上述策略进行调整，确保代码的兼容性和可维护性。

以上就是Node.js中CommonJS与ES模块混合使用的策略与实践的详细内容，更多请关注php中文网其它相关文章！