ES Modules与CommonJS互操作性陷阱解析

在现代JavaScript开发中，ES Modules与CommonJS虽能共存于Node.js，但二者互操作性暗藏多重陷阱：ESM默认导出在require中需通过.default访问，命名导出在CommonJS中几乎不可用，CJS模块被import时仅支持default导入而无法解构命名导出，且循环依赖在两者间行为迥异、极易引发难以调试的运行时错误——这些看似细微的差异，往往成为项目迁移、构建配置或跨系统协作中的“隐形炸弹”，稍有不慎便导致功能异常或打包失败。

在现代JavaScript开发中，ES Modules（ESM）和CommonJS（CJS）是两种主流的模块系统。虽然Node.js已支持两者共存，但它们之间的互操作性存在一些容易被忽视的问题。理解这些陷阱有助于避免运行时错误或打包异常。

默认导出与require的兼容问题

ESM中的默认导出在被CommonJS通过require引入时，行为可能不符合预期。

例如，一个ESM文件：

// math.mjs
export default function add(a, b) {
  return a + b;
}

在CommonJS中引入：

// app.cjs
const add = require('./math.mjs');
console.log(add); // 输出：{ default: [Function: add] }

你不能直接调用add(1, 2)，因为整个模块被包装在default属性下。必须使用add.default(1, 2)才能正确调用。

命名导出在require中不可直接访问

如果ESM使用命名导出：

// utils.mjs
export const PI = 3.14;
export function square(x) { return x * x; }

在CommonJS中：

const utils = require('./utils.mjs');
console.log(utils.PI);        // undefined
console.log(utils.square);    // undefined
console.log(utils);           // {}

这通常是因为ESM模块没有提供正确的命名空间映射。某些情况下Node.js会尝试合成命名空间，但行为不稳定，尤其在动态加载或打包工具中。

CJS模块被import时返回default

当使用ESM语法导入CommonJS模块时，整个模块对象会成为default导出。

// legacy.js
module.exports = { foo: 'bar' };
// index.mjs
import stuff from './legacy.js';
console.log(stuff.foo); // 正确：'bar'
import { foo } from './legacy.js'; // 错误！

这种写法会报错，因为CommonJS没有原生的命名导出机制。你需要始终通过default导入整个对象，再解构使用。

循环依赖行为差异

ESM和CJS处理循环依赖的方式不同。CJS返回的是“当前执行状态”的引用，而ESM使用“实时绑定”。

这意味着在混合使用时，可能出现一边拿到未初始化值，另一边却期望响应式更新的情况。这类问题在大型项目中难以排查，建议尽量避免跨模块系统的循环引用。

基本上就这些常见陷阱。关键是要清楚导入方式和导出形式的匹配关系，尤其是在迁移旧项目或配置构建工具时，稍不注意就会掉进坑里。

到这里，我们也就讲完了《ES Modules与CommonJS互操作性陷阱解析》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！