CommonJS与ESM怎么兼容？

在JavaScript模块化演进中，CommonJS与ESM并非此消彼长的替代关系，而是通过Node.js原生支持的文件扩展名区分（.cjs/.mjs/.js）、package.json的"type"字段配置、动态导入机制（如import()与require的有限互通）、以及Babel/Webpack/Vite等构建工具的双向转译能力，实现了稳健而灵活的长期共存；如今主流npm包普遍同时提供两种格式，既保障了旧项目兼容性，又支持新项目拥抱标准，让开发者得以平滑过渡、按需选择，真正将模块系统的演进转化为生产力而非负担。

在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学习网公众号了解相关技术文章。