module 与 CommonJS 有什么区别
一句话:这不是 TypeScript 发明的分裂,而是 JavaScript 自己历史上先有 CommonJS(Node 的模块方案),后有 ES Module(写进语言标准的模块),TypeScript 作为“编译到各种运行环境”的语言,必须同时服务这两套系统。
一、为什么会分成两套
- 2009:Node.js 选了 CommonJS(
require/module.exports)作为模块方案,那时候 JavaScript 语言本身还没有模块。 - 2012:TypeScript 出生时,能跑 JS 的地方基本只有浏览器(靠 script 标签,没有模块)和 Node(CJS)。TS 的定位是给 JS 加类型再编译回 JS,所以它的
import/export一开始只是语法糖,编译产物是 CJS。 - 2015:ES6(ES2015)把
import/export写进语言标准,这就是 ESM。 - 之后的 Node:从 v12 起实验性支持 ESM,v14 / v16 逐步稳定,v22 起连
require(ESM)也放开了。于是今天两套模块系统在同一个生态里并存。 - TS 视角:TS 不绑定运行时,同一份源码要能编译给 Node、浏览器、Deno、打包器。所以它把“目标模块系统”做成了开关(
module),把“按哪套规则找文件”做成另一个开关(moduleResolution)。
所以答案是:TS 并没有主动分裂,它只是在兼容两个历史阶段。
二、核心区别
| 对比项 | CommonJS(CJS) | ES Module(ESM) |
|---|---|---|
| 语法 | require() / module.exports / exports | import / export |
| 文件判定 | .cjs;package.json 没有 “type”: “module” 时的 .js | .mjs;“type”: “module” 下的 .js |
| 导出性质 | 导出一个对象(快照),重新赋值 module.exports 不会同步给已有引用 | 活绑定(live binding):导出方改变量,导入方能拿到新值 |
| 加载时机 | 运行时同步加载,require 可以写在 if、函数里 | 静态分析,先建依赖图再执行;import 只能在顶层(动态 import() 除外) |
| 顶层 await | 不支持 | 支持 |
| 严格模式 | 默认非严格,顶层 this 指向 module.exports | 默认严格模式,顶层 this 是 undefined |
| 可用变量 | require、module、dirname | 都没有,用 import.meta.url、import.meta.dirname |
| 循环依赖 | 可能拿到“还没填完”的 exports(undefined) | 靠提升 + 活绑定,通常能拿到引用 |
| tree-shaking | 基本不行,打包器只能猜 | 结构是静态的,可以摇树,产物更小 |
| 缓存 | require 有缓存,缓存的是导出对象 | 模块只执行一次,绑定共享 |
补充两点:
- ESM 里相对导入必须写扩展名,CJS 可以省略。
- ESM 里导入 JSON 要用 import attributes:
import data from “./x.json” with { type: “json” }(旧的assert { … }写法已废弃)。
三、TypeScript 里对应的开关
{
"compilerOptions": {
"target": "es2022",
"module": "nodenext", // 输出哪种模块系统
"moduleResolution": "nodenext", // 按哪套规则解析 import
"esModuleInterop": true, // 让 import x from "cjs包" 能正常工作
"verbatimModuleSyntax": true, // 你写 import 就输出 import,不再偷偷换成 require
"strict": true
}
}
要点:
- 写了
import/export不代表运行时就是 ESM:最终输出由module决定。很多“我以为我在写 ESM”的项目,其实编译出来全是require。 - 常用组合:
- 新 Node 项目 / 库:
module: “nodenext”+moduleResolution: “nodenext” - 前端打包(Vite / Webpack / tsup):
module: “esnext”+moduleResolution: “bundler” - 老 Node / 保守项目:
module: “commonjs”+moduleResolution: “node10”,并开esModuleInterop
- CJS 专属的互操作语法:
import x = require(“x”)、export =,声明文件里经常成对出现。
四、什么时候用 module(ESM),什么时候用 CommonJS
优先用 ESM(module: nodenext / esnext)
- 新项目一律优先 ESM,这是语言标准的方向。
- 前端项目:浏览器原生就跑 ESM,打包器也以它为基准。
- 需要 tree-shaking、要发布给现代打包器的库。
- 要用顶层 await、动态
import()做懒加载 / 代码分割。 - Node 18+ 的后端服务,基本可以直接上。
留在 CommonJS(module: commonjs)
- 老项目、依赖链里大量只有 CJS 的包,迁移成本高于收益。
- 需要
require.resolve、条件require、运行时同步加载等 CJS 独有的能力。 - 老版本工具链(老 Jest、部分 ts-node 配置、某些 Electron 场景)仍以 CJS 为默认。
- 需要被老环境直接
require的库。 - 判断标准很简单:只有当目标环境不支持 ESM,或者迁移代价明显过大时,才留在 CJS。
五、互操作与常见坑
- ESM 导入 CJS:可以。默认导入拿到的是
module.exports;具名导入靠静态分析推断,有时拿不到,只能退化成 default 再取属性。 - CJS 里
requireESM:Node 22.12+ / 20.19+ 才默认支持,而且被 require 的 ESM 不能有顶层 await;更早的版本直接报ERRREQUIREESM。 - 双包风险(dual package hazard):同一份代码同时发 CJS 和 ESM 两份,可能被加载成两个互不相干的实例,
instanceof、单例、全局状态都会失效。 - 同一个项目里别混用:Node 依据 package.json 的
“type”决定所有.js的格式,个别文件要例外就用.mts/.cts。 module.exports = X想让 TS 默认导入:需要esModuleInterop(它隐含allowSyntheticDefaultImports)。verbatimModuleSyntax打开后,类型必须写成import type/export type,否则不会被擦除。
六、小结
两套模块系统是 JS 历史留下的既成事实,TS 只是把它们都支持了,并给你 module / moduleResolution 两个开关去选。实践上的取舍:新代码优先 ESM,被老环境绑住才用 CJS;项目内部保持统一,个别文件用 .mts / .cts 破例。