CommonJS与ES模块互操作全解析

编程并不是一个机械性的工作，而是需要有思考，有创新的工作，语法是固定的，但解决问题的思路则是依靠人的思维，这就需要我们坚持学习和更新自己的知识。今天golang学习网就整理分享《JavaScript模块详解：CommonJS与ES模块互操作指南》，文章讲解的知识点主要包括，如果你对文章方面的知识点感兴趣，就不要错过golang学习网，在这可以对大家的知识积累有所帮助，助力开发能力的提升。

Node.js通过文件扩展名、package.json的"type"字段和import()动态导入识别模块类型：".mjs"强制ESM，".cjs"强制CommonJS，"type":"module"使.js按ESM解析；ESM可import CommonJS但仅限default，CommonJS需用import()异步加载ESM。

CommonJS 和 ES 模块不能直接混用，但可以通过配置和约定实现互通 —— 关键不在“怎么写”，而在“怎么告诉 Node.js 这个文件属于哪种模块”。

如何让 Node.js 正确识别模块类型

Node.js 不靠语法判断模块系统，而靠三样东西：文件扩展名、package.json 的 "type" 字段、以及动态导入方式。漏掉任一环都可能触发 ERR_REQUIRE_ESM 或 Cannot use import statement outside a module。

• "type": "module" 设在 package.json 中 → 所有 .js 文件按 ESM 解析（require() 会报错）
• .mjs 后缀 → 强制 ESM，无视 "type"
• .cjs 后缀 → 强制 CommonJS，哪怕 "type": "module"
• import() 动态函数 → 只能加载 ESM（返回 Promise），require() 无法反向加载 ESM

ESM 中导入 CommonJS 模块的正确写法

ESM 可以直接 import CommonJS 模块，但 CommonJS 的 module.exports 会被整个挂到 default 上 —— 命名导入（import { foo } from 'x'）永远失败。

• ✅ 正确：import lodash from 'lodash' → lodash 就是 module.exports 对象
• ✅ 正确：import { default as $ } from 'jquery' → 显式声明 default 绑定
• ❌ 错误：import { debounce } from 'lodash' → 报 Named export 'debounce' not found
• ⚠️ 注意：import * as cjsMod from './legacy.cjs' 得到的是 { default: {...} }，不是扁平命名空间

CommonJS 中加载 ESM 模块的两种可靠方式

require() 无法同步加载 ESM，强行写会直接报错。必须用异步或工具兜底：

• ✅ 动态 import()：const { hello } = await import('./esm-module.mjs') —— 简单、标准、需 async 函数包裹
• ✅ esm 包：require = require('esm')(module); const esm = require('./esm-module.mjs') —— 同步感强，适合旧脚本迁移，但增加运行时依赖
• ❌ 不要用 require('./esm-module.mjs') —— 100% 触发 Must use import to load an ES module

混合项目最易忽略的坑：默认导出 vs 命名导出的双向失配

ESM 的 export default 被 CommonJS require() 加载后，会变成 { default: fn }；反过来，CommonJS 的 module.exports = { a: 1 } 在 ESM 里只能通过 import obj from './x' 访问 obj.a，不能 import { a } from './x'。

• ESM 导出函数：export default function add() {...} → CJS 中要写 const { default: add } = require('./x') 或 const add = require('./x').default
• CJS 导出对象：module.exports = { log() {} } → ESM 中必须 import logger from './x'，再用 logger.log()
• 循环依赖时更危险：CJS 返回执行中对象引用，ESM 是实时绑定，混用可能导致一方读到 undefined

真正卡住人的从来不是语法，而是 Node.js 在解析阶段就根据文件后缀和 "type" 做了硬性分流 —— 写对了代码，配错了类型，照样跑不起来。

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