CommonJS与ESM共存方案解析

在JavaScript模块化演进中，CommonJS与ESM并非水火不容，而是通过一系列机制和工具链实现了共存。Node.js利用`.js`、`.mjs`、`.cjs`文件扩展名区分模块系统，并通过`package.json`中的`type`字段声明默认模块格式。ESM能通过动态`import()`导入CommonJS模块，而CommonJS也能借助`import()`加载ESM。诸如Babel等构建工具更支持双向转换，确保开发者可以使用现代语法进行开发。众多npm包同时提供ESM和CommonJS两种版本，以保证在不同环境下的兼容性。尽管ESM已逐渐成为主流，但CommonJS凭借其简单性和广泛应用，仍将在未来很长一段时间内与ESM并存。

CommonJS与ESM通过文件扩展名、package.json配置、运行时支持及构建工具实现共存。Node.js用.js、.mjs、.cjs区分模块系统，package.json的"type"字段声明默认模块格式，ESM可动态导入CommonJS，CommonJS可通过import()加载ESM，Babel等工具支持双向转换，npm包常同时提供ESM和CommonJS版本，确保兼容性，两者长期并存。

在JavaScript模块化的发展过程中，CommonJS与ESM（ECMAScript Modules）并不是非此即彼的关系，而是通过兼容机制和工具链逐步实现共存。Node.js早期采用CommonJS作为默认模块系统，而浏览器环境和现代JavaScript标准则推动了ESM的普及。两者共存的关键在于运行时支持、文件扩展名区分、package.json配置以及构建工具的转换能力。

文件格式与加载方式的区分

Node.js通过文件扩展名来决定使用哪种模块系统：

• .js 文件默认按 CommonJS 处理，除非 package.json 中设置了 "type": "module"
• .mjs 文件强制使用 ESM，无论配置如何
• .cjs 文件强制使用 CommonJS，即使 type 为 module

这种设计让开发者可以在同一个项目中混合使用两种模块语法，只需正确命名文件即可。

package.json 中的模块类型声明

通过在 package.json 中设置 "type": "module"，整个项目默认使用 ESM；如果不设置或设为 "commonjs"，则使用 CommonJS。这使得包作者可以明确声明其发布的模块所使用的规范，消费方据此进行导入。

例如，一个发布为 ESM 的包可以在内部使用 import/export，而另一个依赖它的旧项目仍可通过动态 import() 或打包工具来兼容使用。

跨模块系统的互操作性

Node.js 提供了跨模块系统的加载能力：

• ESM 中可以通过 dynamic import('fs') 使用 CommonJS 模块（静态 import 不支持）
• CommonJS 中可以用 require() 直接引入 ESM 模块（但不推荐，可能引发异步问题）
• 更稳妥的方式是使用顶层 await 配合 import() 在 CommonJS 中加载 ESM

这种有限的互通性缓解了迁移过程中的阻塞问题。

构建工具与转译的支持

像 Babel、TypeScript、Webpack、Vite 等工具能够在编译阶段将 ESM 转为 CommonJS，或反之。这使得开发者可以统一使用现代语法开发，再根据目标环境输出合适的格式。

很多 npm 包同时提供两个版本：一个 ESM 格式（放在 esm/ 或通过 exports 字段导出），一个 CommonJS 格式（main 字段指向 cjs 文件），确保不同环境都能正确加载。

基本上就这些。CommonJS 与 ESM 的共存不是靠一方取代另一方，而是通过语言特性、运行时规则和生态工具共同协作实现的平滑过渡。随着 Node.js 对 ESM 支持趋于稳定，越来越多项目转向 ESM，但 CommonJS 因其简单性和广泛存量仍在长期共存。

今天关于《CommonJS与ESM共存方案解析》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！