Node.js模块化兼容：CommonJS与ESM混合使用指南-js教程-PHP中文网

Node.js模块化兼容：CommonJS与ESM混合使用指南

心靈之曲

发布： 2025-09-15 10:29:17

原创

302人浏览过

Node.js模块化兼容：CommonJS与ESM混合使用指南

本教程旨在解决Node.js项目中CommonJS与ES模块混用时的兼容性问题。我们将详细探讨在ES模块环境下如何正确导入CommonJS模块，以及在CommonJS环境下如何动态导入ES模块，提供具体的代码示例和注意事项，帮助开发者理解并有效管理不同模块系统间的交互，确保项目顺利运行。

在node.js生态系统中，存在两种主要的模块系统：commonjs (cjs) 和 es modules (esm)。commonjs是node.js早期采用的模块标准，使用require()和module.exports。而es modules是javascript语言的官方模块标准，使用import和export。当一个项目需要同时使用这两种模块系统编写的库时，开发者常常会遇到兼容性挑战，例如syntaxerror: cannot use import statement outside a module或referenceerror: require is not defined in es module scope。理解如何在不同模块环境中正确地导入和导出是解决这些问题的关键。

理解Node.js模块类型配置

在深入解决方案之前，首先需要明确项目的模块类型配置。Node.js通过package.json文件中的"type"字段来确定项目的默认模块系统：

"type": "commonjs" (或不指定，这是默认行为): 项目中的.js文件被视为CommonJS模块。
"type": "module": 项目中的.js文件被视为ES模块。

这种配置决定了您在文件中使用import/export还是require()/module.exports。然而，在实际开发中，我们经常需要在一个ES模块中引入CommonJS库，或者在一个CommonJS模块中引入ES模块库。

在ES模块中使用CommonJS模块

当您的项目配置为ES模块（"type": "module"）时，您可以使用import语句来导入CommonJS模块。但需要注意的是，CommonJS模块只有一个默认导出（module.exports），因此不能使用命名导入。

导入方式：

您应该使用默认导入语法来引入CommonJS模块。

// package.json 配置为 "type": "module"

// 示例：导入 prompt-sync (CommonJS 模块)
// 方式一：使用默认导入
import prompt from 'prompt-sync';

// 方式二：显式指定默认导出
// import { default as prompt } from 'prompt-sync';

// 使用导入的 CommonJS 模块
const userInput = prompt('请输入您的姓名：');
console.log(`您好，${userInput}`);

登录后复制

解释：

CommonJS模块的module.exports会被ES模块系统视为其默认导出。因此，无论CommonJS模块内部如何定义导出（例如module.exports.foo = bar），当被ES模块导入时，您只能通过默认导入（import name from 'module'）来获取module.exports的整个值。尝试使用命名导入（import { someNamedExport } from 'commonjs-module'）将会导致SyntaxError: Named export '...' not found。

在CommonJS模块中使用ES模块

当您的项目配置为CommonJS（"type": "commonjs"或未指定）时，您不能直接使用require()来导入ES模块。Node.js会抛出Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported。在这种情况下，您需要使用动态import()表达式。

腾讯混元

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

查看详情

导入方式：

动态import()是一个异步操作，它返回一个Promise，该Promise解析为一个模块对象。因此，您需要使用await关键字（在async函数中）或.then()方法来处理这个Promise。

// package.json 配置为 "type": "commonjs" (或未指定)

// 示例：导入 load-json-file (ES 模块)

async function processJsonFile() {
    try {
        // 动态导入 ES 模块
        const loadJsonFileModule = await import('load-json-file');

        // loadJsonFileModule 是一个模块对象，其命名导出作为属性
        const jsonData = await loadJsonFileModule.loadJsonFile('./data.json');
        console.log('JSON 数据:', jsonData);

    } catch (error) {
        console.error('导入或处理JSON文件失败:', error);
    }
}

// 假设 data.json 文件存在，内容如：{"name": "Node.js", "version": "1.0"}
// data.json
// {
//   "name": "Node.js",
//   "version": "1.0"
// }

processJsonFile();

// 如果您不想使用 async/await，也可以使用 .then()
/*
import('load-json-file')
    .then(loadJsonFileModule => {
        return loadJsonFileModule.loadJsonFile('./data.json');
    })
    .then(jsonData => {
        console.log('JSON 数据 (then):', jsonData);
    })
    .catch(error => {
        console.error('导入或处理JSON文件失败 (then):', error);
    });
*/

登录后复制

解释：

动态导入: import('module-name')表达式在运行时加载指定的ES模块。
Promise: 它返回一个Promise，因此必须使用await或.then()来等待模块加载完成。
模块对象: Promise解析后得到的是一个模块对象，这个对象包含了ES模块的所有命名导出作为其属性。例如，如果ES模块导出了export function loadJsonFile() { ... }，那么在CommonJS中通过动态导入得到的loadJsonFileModule对象将具有一个loadJsonFileModule.loadJsonFile属性。

注意事项：

async函数: 如果使用await，您的代码必须在一个async函数中。在顶层作用域使用await需要Node.js版本14.8.0及以上，并且需要将文件类型设置为"type": "module"。然而，我们这里讨论的是CommonJS环境，所以通常需要将await封装在一个async函数中。
错误处理: 由于import()是异步操作，建议使用try...catch或.catch()来处理潜在的加载或执行错误。

总结与最佳实践

在Node.js中混合使用CommonJS和ES模块是可行的，但需要理解其背后的机制和限制：

ES模块导入CommonJS模块： 使用默认导入语法（import name from 'commonjs-module'），因为CommonJS模块只有一个默认导出。
CommonJS模块导入ES模块： 使用动态import()表达式（await import('es-module')），它返回一个Promise，解析后得到一个包含ES模块所有命名导出的模块对象。

推荐实践：