Node.js中CommonJS与ES Modules混合使用策略及实践

在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）。

腾讯混元

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

65

查看详情

问题描述： 直接使用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();

注意事项与最佳实践

1. package.json的"type"字段至关重要： 明确你的主入口文件或大部分文件将运行在哪种模块上下文中。这有助于避免不必要的错误。
2. 动态import()的异步性： 在CJS中导入ESM时，务必记住import()返回的是Promise。这意味着你通常需要在async函数中使用await，或者使用.then()方法来处理异步结果。
3. CJS模块的默认导出： 当ESM导入CJS模块时，CJS的module.exports会成为ESM的默认导出。如果module.exports是一个函数或一个对象，你就可以直接通过默认导入来使用它。
4. ESM的具名导出： 当CJS通过动态import()导入ESM时，ESM的具名导出将作为返回模块对象的属性。
5. 统一模块系统： 尽管Node.js提供了互操作性机制，但从长远来看，如果可能，尽量将项目中的所有模块统一为ES Modules。这可以简化模块管理，并利用ESM的静态分析优势。对于遗留的CJS库，可以考虑寻找其ESM版本，或使用工具进行转换。
6. 文件扩展名： 即使"type": "module"，你也可以使用.cjs扩展名来强制文件作为CommonJS处理。反之，即使"type": "commonjs"，你也可以使用.mjs扩展名来强制文件作为ES Module处理。这为混合项目提供了更大的灵活性。

总结

Node.js中的CommonJS和ES Modules虽然各有特点，但通过合理的配置和正确的导入语法，它们可以很好地协同工作。在ES Module环境中，通过默认导入CJS模块；在CommonJS环境中，通过动态import()导入ES Module。掌握这些策略，将帮助开发者在面对混合模块类型的项目时，能够游刃有余地构建稳定且高效的Node.js应用。

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