Node.js中CommonJS与ES模块混合使用指南

在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模块。

腾讯混元

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

65

查看详情

导入方式：

要从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。

注意事项与最佳实践

1. 统一模块系统： 对于新项目，强烈建议选择一种模块系统并坚持使用。ES Modules是JavaScript的未来标准，提供更好的静态分析和摇树优化能力。如果可能，将所有代码和依赖迁移到ESM是最佳实践。
2. package.json的"type"字段： 正确配置"type"字段至关重要。它决定了Node.js如何解析你的.js文件。
   • "type": "module"：.js文件默认为ESM。
   • "type": "commonjs" 或不设置：.js文件默认为CJS。
   • 你也可以通过文件扩展名覆盖默认行为：.mjs文件总是ESM，.cjs文件总是CJS。
3. 动态import()的异步性： 记住动态import()返回的是Promise。这意味着你不能在同步代码块中直接使用它的结果，必须配合async/await或.then()。
4. 命名导出与默认导出： 在ESM中导入CJS时，CJS的module.exports被视为ESM的默认导出。在CJS中动态导入ESM时，ESM的命名导出会作为模块对象的属性。

总结

Node.js中CommonJS与ES模块的混合使用是开发过程中常见的场景。通过理解package.json中的"type"配置以及掌握在ES模块中导入CommonJS的默认导出机制，和在CommonJS中动态导入ES模块的异步import()表达式，开发者可以有效地桥接这两种模块系统。尽管存在这些兼容性方案，但为了项目的可维护性和未来发展，尽可能统一采用ES模块仍然是推荐的最佳实践。

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