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，强行写会直接报错。必须用异步或工具兜底：
立即学习“Java免费学习笔记（深入）”；
- ✅ 动态
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" 做了硬性分流 —— 写对了代码，配错了类型，照样跑不起来。
