Node.js / 系统课时

选择 CommonJS 或 ES 模块

选择 CommonJS 或 ES 模块

CommonJS 与 ES 模块都能组织 Node.js 代码,但它们的文件判定、语法和互操作方式不同。本课给出可直接执行的对照,并提供新项目、旧项目和发布 npm 包时的选型检查方法。

学习目标

  • 能根据扩展名和 package.json 判断文件按 CommonJS 还是 ESM 解析。
  • 能写出 require/module.exports 与 import/export 的基础等价用法。
  • 能根据项目现状、依赖兼容性和发布目标选择模块体系。

先把模块格式写明确

不要让同一份 .js 的解析方式依赖环境猜测。最清楚的做法是:.mjs 明确表示 ESM,.cjs 明确表示 CommonJS;使用 .js 时,在最近一层 package.json 中显式声明 type。

json
{
  "name": "module-choice-demo",
  "private": true,
  "type": "module"
}

这份配置让同一包范围内的 .js 按 ESM 解析。如果项目主体仍是 CommonJS,可显式使用 "type": "commonjs",或把需要固定为 CommonJS 的个别文件命名为 .cjs。

文件或配置 解析方式
worker.mjs ESM
worker.cjs CommonJS
.js + "type": "module" ESM
.js + "type": "commonjs" CommonJS

对照两种基础写法

先看 ESM。创建 esm-demo.mjs,使用 export 暴露函数,文件本身同时作为可运行入口输出结果。

js
const double = (value) => value * 2;

export { double };

console.log(double(21));

运行:

bash
node esm-demo.mjs

预期输出:

text
42

再看 CommonJS。创建 commonjs-demo.cjs,把同一个函数放到 module.exports 中。

js
const double = (value) => value * 2;

module.exports = { double };

console.log(double(21));

运行:

bash
node commonjs-demo.cjs

预期输出:

text
42

两种模块体系都能完成依赖拆分。区别在于 ESM 使用 import/export,CommonJS 使用 require()/module.exports;选型时更重要的是项目现有边界和消费者兼容性。

处理混用与迁移边界

从 ESM 使用 CommonJS 模块时,最稳妥的基础做法通常是默认导入其 module.exports。从 CommonJS 加载 ESM 时,如果项目需要覆盖多个 Node.js LTS 版本,优先以动态 import() 作为兼容基线,并针对目标 Node 版本单独验证。

迁移一个已有 CommonJS 项目时,可以按下面顺序降低风险:

  1. 先盘点 require()、module.exports、__dirname、测试配置和启动脚本。
  2. 选一个依赖边界清晰的目录改为 .mjs,或拆成独立子包并设置 "type": "module"。
  3. 先让单元测试、命令行启动和生产构建全部通过,再扩大迁移范围。
  4. 不要直接在根目录切换 type 后一次修完所有报错;这会把模块格式、路径解析和工具链问题混在一起。

对于库代码,还要检查“同一个包被 ESM 与 CommonJS 两条入口各加载一次”的情况。若两个入口各自保存单例状态,消费者可能得到两份状态副本,因此双入口包必须做跨入口测试。

按项目条件做选择

新建且只面向现代 Node.js 的应用,可以直接采用 ESM,并在 package.json 明确 "type": "module"。已有大量 CommonJS 文件和旧插件的项目,可以继续使用 CommonJS,再按依赖边界渐进迁移。

项目条件 更合适的起点 需要检查的具体项
新应用,代码从零开始 ESM 依赖是否支持 ESM;测试与打包工具是否按 ESM 配置
老项目,已有大量 require() CommonJS 延续或渐进迁移 __dirname、动态加载、测试脚本、启动脚本
npm 包只服务现代消费者 ESM 可行 engines.node、导出路径、消费者构建工具
npm 包同时服务 ESM 与 CommonJS 消费者 双入口或兼容层 分别测试 import 与 require;检查共享状态是否被复制

发布双入口包时,至少建立两个最小消费项目:一个只用 ESM import,另一个只用 CommonJS require,分别执行安装、导入和核心 API 调用。两边都通过后,再把它们加入 CI,避免后续构建只修好其中一种入口。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

选择 CommonJS 或 ES 模块

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通