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。
{
"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 暴露函数,文件本身同时作为可运行入口输出结果。
const double = (value) => value * 2;
export { double };
console.log(double(21));运行:
node esm-demo.mjs预期输出:
42再看 CommonJS。创建 commonjs-demo.cjs,把同一个函数放到 module.exports 中。
const double = (value) => value * 2;
module.exports = { double };
console.log(double(21));运行:
node commonjs-demo.cjs预期输出:
42两种模块体系都能完成依赖拆分。区别在于 ESM 使用 import/export,CommonJS 使用 require()/module.exports;选型时更重要的是项目现有边界和消费者兼容性。
处理混用与迁移边界
从 ESM 使用 CommonJS 模块时,最稳妥的基础做法通常是默认导入其 module.exports。从 CommonJS 加载 ESM 时,如果项目需要覆盖多个 Node.js LTS 版本,优先以动态 import() 作为兼容基线,并针对目标 Node 版本单独验证。
迁移一个已有 CommonJS 项目时,可以按下面顺序降低风险:
- 先盘点
require()、module.exports、__dirname、测试配置和启动脚本。 - 选一个依赖边界清晰的目录改为
.mjs,或拆成独立子包并设置"type": "module"。 - 先让单元测试、命令行启动和生产构建全部通过,再扩大迁移范围。
- 不要直接在根目录切换
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,避免后续构建只修好其中一种入口。