typescript:module与cjs的区别

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 { … } 写法已废弃)。
{
  "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,见 什么是mts文件。
  • CJS 专属的互操作语法:import x = require(“x”)、export =,声明文件里经常成对出现。

优先用 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;更早的版本直接报 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 破例。

相关:什么是mts文件、import / export 语法、编译配置

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • typescript/module与cjs的区别.txt
  • 最后更改: 2026/10/10 22:40
  • 由 张叶安