type": "module"下CommonJS互操作问题

Question

在 `type: "module"` 的 Node.js 项目中，CommonJS 模块（如使用 `require()` 和 `module.exports`）与 ES 模块（ESM）存在互操作限制。常见问题是：无法直接通过 `import` 语法导入 CommonJS 模块的默认导出，或在 ESM 中正确解析 `require`。例如，`import _ from 'lodash'` 可能因模块解析策略不同导致运行时错误。此外，动态导入需用 `await import()`，且 `__dirname`、`__filename` 在 ESM 中不可用，引发路径处理异常。如何平滑兼容旧有 CommonJS 模块成为典型痛点。

Answer 1

1. 问题背景与模块系统演进

Node.js 自 12 版本起正式支持 ES 模块（ESM），通过在 package.json 中设置 "type": "module" 启用。然而，长期以来 Node.js 使用的是 CommonJS（CJS）模块系统，依赖 require() 和 module.exports。这导致在现代 ESM 项目中引入遗留 CJS 模块时出现兼容性挑战。

典型表现包括：

• import _ from 'lodash' 可能无法正确解析默认导出
• require() 在 ESM 文件中非法使用
• 动态导入必须使用 await import() 异步语法
• __dirname、__filename 在 ESM 中不可用
• CJS 的 module.exports = value 被 ESM 视为 default 导出的包装对象

2. 核心差异分析：CommonJS vs ES 模块

特性	CommonJS (CJS)	ES 模块 (ESM)
导入方式	const mod = require('mod')	import mod from 'mod'
导出方式	module.exports = value	export default value
加载机制	同步	静态解析 + 异步加载
顶层 this	undefined	module 对象
__dirname	可用	不可用
动态导入	require('./dynamic')	await import('./dynamic')

3. 常见互操作陷阱与运行时错误

当在 ESM 项目中尝试导入 CJS 模块时，Node.js 会自动进行模块转换，但语义上存在歧义。例如：

import _ from 'lodash'; // 可能失败或返回 { default: _ }

这是因为 CJS 没有“默认导出”概念，Node.js 将整个 module.exports 包装为 default 属性。因此实际结构为：

{
  default: {
    forEach: Function,
    map: Function,
    // ...
  }
}

若未启用命名空间解析，则需写成：

import lodash from 'lodash';
const _ = lodash.default || lodash; // 兼容处理

4. 动态导入与异步上下文处理

在 ESM 中，动态路径导入必须使用 await import()，且只能在 async 函数内执行：

const loadConfig = async (env) => {
  const module = await import(`./config.${env}.js`);
  return module.default;
};

该限制源于 ESM 的静态分析特性，不允许运行时动态解析依赖图。此外，传统 CJS 风格的条件 require 在 ESM 中无法直接迁移。

5. 路径处理替代方案：重建 __dirname 与 __filename

由于 ESM 不提供 __dirname 和 __filename，需通过 import.meta.url 手动构造：

import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

console.log(__dirname); // 输出当前文件所在目录

此模式应封装为工具函数或全局辅助模块，便于跨项目复用。

6. 解决方案全景图：兼容策略与工程实践

1. 统一模块规范：逐步将 CJS 迁移至 ESM，使用 .mjs 或配置 "type": "module"
2. 利用 createRequire 在 ESM 中安全调用 CJS：

import { createRequire } from 'module';
const require = createRequire(import.meta.url);

const config = require('./config.json'); // 正常加载 JSON/CJS

1. 配置 exports 字段实现双端兼容发布
2. 使用 Babel / TypeScript 编译层抹平差异
3. 在 package.json 中明确指定 main 与 module 入口

7. 架构级建议：渐进式迁移路径

graph TD
    A[现有CJS代码库] --> B{启用"type": "module"}
    B --> C[识别核心CJS依赖]
    C --> D[封装CJS模块为ESM适配层]
    D --> E[替换 require 为 createRequire]
    E --> F[重构路径逻辑使用 import.meta.url]
    F --> G[测试互操作稳定性]
    G --> H[全面切换至ESM语法]
    H --> I[发布双格式包]

该流程确保团队可在不中断服务的前提下完成模块系统升级，尤其适用于微服务架构中的独立模块演进。