====== 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''、''__filename'' | 都没有,用 ''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'' - 个别文件必须换格式时用扩展名强制:''.mts'' 强制 ESM、''.cts'' 强制 CJS,见 [[typescript:什么是mts文件]]。 - 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 里 ''require'' ESM**:Node 22.12+ / 20.19+ 才默认支持,而且被 require 的 ESM 不能有顶层 await;更早的版本直接报 ''ERR_REQUIRE_ESM''。 - **双包风险(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'' 破例。** 相关:[[typescript:什么是mts文件]]、[[typescript:导入模块|import / export 语法]]、[[typescript:第十章_编译配置|编译配置]]