Nicholas Qin1. 当两种模块系统相遇：Node.js的模块化演进之路
2018年5月，Node.js 10.12.0版本首次引入实验性ES模块支持时，整个JavaScript社区都意识到一个新时代即将来临。作为长期使用Node.js的开发者，我清楚地记得当时团队内部关于是否要迁移到ESM的激烈讨论。如今六年过去，ESM已成为现代JavaScript开发的标配，但CommonJS（CJS）依然在大量遗留系统中运行良好。这种双模块系统共存的局面，既是Node.js兼容性的体现，也是每个Node.js开发者必须面对的工程现实。
在Node.js诞生之初，CommonJS模块系统是其核心设计之一。这种同步加载的模块化方案完美契合了服务器端JavaScript的需求，通过require()和module.exports的简单组合，开发者可以轻松组织代码结构。但随着前端生态的快速发展，特别是ECMAScript标准在2015年正式推出原生模块系统（ES Modules）后，Node.js面临着与浏览器生态统一的重要挑战。
关键转折点出现在Node.js 12和14版本，ESM支持从实验性功能逐步稳定，最终在Node.js 15.3.0版本中取消了实验性标记。这个过程中，Node.js团队需要解决CJS和ESM在加载机制、解析算法和运行时行为上的根本差异。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 语法层面的直观对比：写法的分水岭
2.1 导入导出语法的差异
CommonJS使用经典的require函数进行模块导入，导出则通过module.exports或exports对象实现。这种语法源自Node.js早期设计，具有明确的动态特性：
javascript复制// CJS导入
const fs = require('fs');
const { readFile } = require('fs').promises;
// CJS导出
module.exports = function() { /*...*/ };
exports.helper = function() { /*...*/ };
相比之下，ESM采用了ECMAScript标准语法，使用import和export关键字，这种静态语法设计使得模块依赖关系可以在代码执行前确定：
javascript复制// ESM导入
import fs from 'fs';
import { readFile } from 'fs/promises';
import * as path from 'path';
// ESM导出
export default function() { /*...*/ };
export const helper = () => { /*...*/ };
2.2 文件扩展名与package.json配置
Node.js通过以下规则区分模块类型：
.cjs文件始终作为CJS模块解析.mjs文件始终作为ESM模块解析.js文件默认作为CJS模块，除非最近的package.json中包含"type": "module"
在混合项目中，package.json配置至关重要：
json复制{
"type": "module", // 所有.js文件视为ESM
"main": "./index.cjs", // 兼容旧版本Node.js
"exports": {
".": {
"require": "./index.cjs",
"import": "./index.mjs"
}
}
}
3. 运行时特性的深度对比
3.1 加载机制的本质区别
CJS模块是动态加载的运行时结构，模块代码在require()调用时执行，导出对象可以在运行时动态修改。这种灵活性带来了诸如热更新等高级用法，但也限制了静态分析和优化可能性。
ESM则是静态的编译时结构，模块依赖关系在执行前就已经确定。这种设计带来了三个重要特性：
- 导入提升（Hoisting）：
import语句会被提升到模块作用域顶部 - 只读视图：导入的绑定是只读的，不同于CJS的可变引用
- 静态可分析性：工具链可以准确构建完整的依赖图
3.2 顶层await的独占特性
ESM支持在模块顶层直接使用await，这在异步初始化场景中极为便利：
javascript复制// 仅在ESM中有效
import db from 'database';
await db.connect(); // 模块加载时会等待连接完成
而CJS中要实现类似效果，必须使用IIFE或立即调用的async函数：
javascript复制// CJS中的变通方案
const db = require('database');
(async () => {
await db.connect();
})();
3.3 解析算法的差异对比
| 特性 | CommonJS | ESM |
|---|---|---|
| 文件扩展名 | .js, .cjs, .json | .js, .mjs, .json (需配置) |
| 目录索引 | 查找index.js | 查找index.mjs或package.json导 |
| 路径解析 | 支持省略扩展名 | 必须完整路径或配置解析规则 |
| 循环依赖处理 | 部分支持但可能导致状态不一致 | 完善的静态绑定机制 |
| 动态导入 | require()任意位置 | import()动态导入函数 |
4. 互操作性实践：跨越模块边界
4.1 CJS调用ESM的约束与方案
由于ESM的异步特性，CJS模块不能直接requireESM模块，但可以通过动态导入：
javascript复制// 在CJS中加载ESM
async function loadESM() {
const esModule = await import('./es-module.mjs');
esModule.default();
}
4.2 ESM中使用CJS的注意事项
ESM可以导入CJS模块，但存在以下限制：
- CJS导出的默认导出会是
module.exports的整个对象 - 命名导入需要通过解构赋值实现
- 无法获得ESM的实时绑定特性
javascript复制// ESM中导入CJS
import cjsModule from './commonjs.cjs';
// 等价于 const cjsModule = require('./commonjs.cjs')
4.3 双模式模块的创建策略
对于需要同时支持CJS和ESM的库，推荐以下项目结构：
code复制your-package/
├── lib/ # 编译后的CJS代码
│ └── index.js
├── esm/ # 编译后的ESM代码
│ └── index.js
├── package.json # 配置exports字段
└── src/ # 源代码(通常用ESM)
package.json关键配置示例：
json复制{
"exports": {
".": {
"require": "./lib/index.js",
"import": "./esm/index.js"
}
}
}
5. 工程实践中的痛点与解决方案
5.1 类型系统的兼容处理
在TypeScript项目中，模块类型的正确声明至关重要。对于双模式模块，需要配置不同的types字段：
json复制{
"exports": {
".": {
"require": {
"types": "./lib/index.d.ts",
"default": "./lib/index.js"
},
"import": {
"types": "./esm/index.d.ts",
"default": "./esm/index.js"
}
}
}
}
5.2 测试框架的适配挑战
Jest等测试工具需要特殊配置才能处理ESM：
javascript复制// jest.config.js
module.exports = {
preset: 'ts-jest/presets/default-esm',
globals: {
'ts-jest': {
useESM: true,
},
},
moduleNameMapper: {
'^(\\.{1,2}/.*)\\.js$': '$1',
},
};
5.3 性能优化的不同路径
CJS的缓存机制：
- 每个模块首次加载后会被缓存
- 清除缓存需要直接操作
require.cache
ESM的优化机会：
- 利用静态分析进行Tree Shaking
- 预加载模块：
<link rel="modulepreload">(浏览器环境) - V8编译缓存机制
5.4 调试技巧的差异
CJS模块在调试时：
- 可以直接在require语句后设置断点
- 修改模块后需要清除缓存才能看到变化
ESM模块调试注意：
- Chrome DevTools对ESM源映射支持更好
- 动态import()的断点需要设置在Promise回调内
- Node.js的--loader钩子可以拦截模块加载过程
6. 迁移策略与未来展望
6.1 渐进式迁移路线图
-
评估阶段：
- 使用
"type": "module"标记新文件 - 保持现有CJS模块不变
- 通过ESLint检测潜在问题
- 使用
-
过渡阶段：
- 将工具链更新至支持ESM的版本
- 使用动态import()实现模块互通
- 逐步转换工具脚本为ESM
-
完成阶段：
- 统一使用ESM语法
- 配置完整的exports字段
- 移除所有CJS特定代码
6.2 工具链的选择与配置
现代构建工具对ESM的支持情况：
- Webpack 5+：原生支持ESM作为输入和输出
- Rollup：专为ESM设计，输出格式灵活
- Vite：基于原生ESM的开发服务器
- esbuild：极速的ESM打包工具
配置示例（vite.config.js）：
javascript复制import { defineConfig } from 'vite';
export default defineConfig({
build: {
target: 'esnext',
rollupOptions: {
output: {
format: 'esm',
entryFileNames: '[name].js',
chunkFileNames: '[name].js'
}
}
}
});
6.3 生态系统的最新动态
Node.js核心团队正在推进的改进：
- 更完善的加载器API（--experimental-loader）
- 模块自定义钩子的标准化
- WASM模块的集成支持
- 更好的ESM和CJS互操作体验
社区工具的发展方向：
- 更智能的CJS到ESM转换工具（如lebab）
- 支持双模块的脚手架模板
- 改进的依赖分析工具
在大型项目中同时使用两种模块系统的经历让我深刻体会到，理解CJS和ESM的差异不是学术练习，而是日常开发的必备技能。特别是在处理第三方依赖时，一个常见的陷阱是假设所有依赖都已迁移到ESM——实际上许多流行库仍以CJS为主。我的经验法则是：新项目直接采用ESM，遗留项目逐步迁移，而对于依赖库，永远检查其package.json中的exports字段。