CommonJS与ESM共存方案解析

golang学习网今天将给大家带来《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 因其简单性和广泛存量仍在长期共存。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~