Node.jsCommonJS与ESM混合使用指南

本文旨在解决Node.js项目中CommonJS与ES模块混用时的兼容性问题，提供一份详细的Node.js CommonJS与ESM混合使用教程，助力开发者有效管理不同模块系统间的交互。文章深入探讨了在ES模块环境下如何正确导入CommonJS模块（使用默认导入语法），以及在CommonJS环境下如何通过动态`import()`表达式导入ES模块，并附带了代码示例和注意事项，避免`SyntaxError`和`ReferenceError`等常见错误。同时，强调了理解Node.js模块类型配置的重要性，并给出了保持模块系统一致性、理解模块边界的最佳实践建议，帮助开发者构建健壮灵活的应用。

本教程旨在解决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);
    });
*/

解释：

1. 动态导入: import('module-name')表达式在运行时加载指定的ES模块。
2. Promise: 它返回一个Promise，因此必须使用await或.then()来等待模块加载完成。
3. 模块对象: 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模块是可行的，但需要理解其背后的机制和限制：

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

推荐实践：

• 保持一致性： 尽可能在一个项目中统一使用一种模块系统。如果可能，将所有代码转换为ES模块，因为这是JavaScript的未来标准。
• 理解模块边界： 清楚地知道哪些库是CommonJS，哪些是ES模块，这有助于选择正确的导入方法。
• 关注错误信息： Node.js的错误信息通常非常明确，会指导您如何解决模块导入问题。

通过掌握这些兼容性策略，开发者可以有效地在Node.js项目中整合不同模块系统的库，从而避免常见的导入错误，并构建更加健壮和灵活的应用。

今天关于《Node.jsCommonJS与ESM混合使用指南》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！