一句话:这不是 TypeScript 发明的分裂,而是 JavaScript 自己历史上先有 CommonJS(Node 的模块方案),后有 ES Module(写进语言标准的模块),TypeScript 作为“编译到各种运行环境”的语言,必须同时服务这两套系统。
require / module.exports)作为模块方案,那时候 JavaScript 语言本身还没有模块。import / export 一开始只是语法糖,编译产物是 CJS。import / export 写进语言标准,这就是 ESM。require(ESM) 也放开了。于是今天两套模块系统在同一个生态里并存。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 有缓存,缓存的是导出对象 | 模块只执行一次,绑定共享 |
补充两点:
import data from “./x.json” with { type: “json” }(旧的 assert { … } 写法已废弃)。{
"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。module: “nodenext” + moduleResolution: “nodenext”module: “esnext” + moduleResolution: “bundler”module: “commonjs” + moduleResolution: “node10”,并开 esModuleInteropimport x = require(“x”)、export =,声明文件里经常成对出现。
优先用 ESM(module: nodenext / esnext)
import() 做懒加载 / 代码分割。
留在 CommonJS(module: commonjs)
require.resolve、条件 require、运行时同步加载等 CJS 独有的能力。require 的库。module.exports;具名导入靠静态分析推断,有时拿不到,只能退化成 default 再取属性。require ESM:Node 22.12+ / 20.19+ 才默认支持,而且被 require 的 ESM 不能有顶层 await;更早的版本直接报 ERRREQUIREESM。instanceof、单例、全局状态都会失效。“type” 决定所有 .js 的格式,个别文件要例外就用 .mts / .cts。module.exports = X 想让 TS 默认导入:需要 esModuleInterop(它隐含 allowSyntheticDefaultImports)。verbatimModuleSyntax 打开后,类型必须写成 import type / export type,否则不会被擦除。
两套模块系统是 JS 历史留下的既成事实,TS 只是把它们都支持了,并给你 module / moduleResolution 两个开关去选。实践上的取舍:新代码优先 ESM,被老环境绑住才用 CJS;项目内部保持统一,个别文件用 .mts / .cts 破例。