从CommonJS到ES Modules：一份给Node.js开发者的平滑迁移指南（含package.json配置）

从CommonJS到ES Modules：Node.js模块化迁移实战手册

模块化演进与工程化挑战

十年前，当Ryan Dahl首次发布Node.js时，CommonJS模块系统凭借其同步加载特性成为服务端JavaScript的标准。时过境迁，ES Modules作为ECMAScript官方标准逐渐崭露头角。这种演进不仅仅是语法差异，更代表着从服务端优先到全栈统一的范式转变。

在混合开发环境中，我们常会遇到这样的场景：在维护的旧项目中引入了一个现代前端库，却在运行时遭遇ReferenceError: require is not defined的报错；或者尝试在ESM文件中使用__dirname时发现这个CommonJS环境下的常用变量突然失效。这些冲突背后，是两种模块系统在解析机制、加载方式和作用域处理上的根本差异：

• 加载时机：CommonJS动态加载 vs ESM静态解析
• 作用域隔离：CommonJS模块包裹函数 vs ESM严格模式
• 元数据访问：require.cachevsimport.meta
• 文件扩展名：.js的歧义性催生.mjs/.cjs规范

// 典型混合环境报错示例 import { readFile } from 'fs/promises' const legacyConfig = require('./config') // 在ESM文件中报错

渐进式迁移策略设计

1. 环境准备与兼容性检查

开始迁移前，需要确认运行环境支持情况。Node.js从12版本开始实验性支持ESM，16版本后达到生产就绪状态。建议使用LTS版本并检查以下配置：

$ node --version # 需≥14.18.0或≥16.0.0 $ npm init -y # 确保package.json存在

关键兼容性矩阵：

2. package.json配置策略

package.json是迁移的指挥中心，其配置直接影响模块解析行为。核心字段包括：

{ "type": "module", // 全局启用ESM "exports": { ".": { "require": "./dist/cjs/index.js", // CJS入口 "import": "./dist/esm/index.mjs" // ESM入口 } }, "scripts": { "build": "tsc && rollup -c", "start": "node --experimental-specifier-resolution=node src/index.js" } }

注意：当"type": "module"时，所有.js文件将被视为ESM模块。此时若需要保留某些CommonJS模块，应使用.cjs扩展名。

3. 双模式兼容实现方案

动态导入桥接技术

import()动态导入语法是连接两种模块系统的金钥匙。通过它可以在ESM环境中加载CJS模块，反之亦然：

// ESM中使用CJS模块 async function loadLegacyModule() { const { legacyFunction } = await import('./legacy.cjs') return legacyFunction() } // CJS中使用ESM模块 import('modern.mjs').then(module => { module.default() }).catch(err => { console.error('模块加载失败:', err) })

文件扩展名策略

• .mjs：强制视为ESM模块
• .cjs：强制视为CommonJS模块
• .js：根据最近的package.json中type字段决定

推荐目录结构示例：

project/ ├── lib/ │ ├── modern.mjs # 纯ESM模块 │ └── legacy.cjs # 纯CommonJS模块 ├── src/ │ └── hybrid.js # 受package.json type影响 └── package.json

高级配置与工具链集成

1. Babel转译方案

对于需要支持多环境的项目，Babel提供了灵活的转译方案。关键配置项：

// babel.config.json { "presets": [ ["@babel/preset-env", { "targets": { "node": "current" }, "modules": "auto" // 自动识别转换模式 }] ], "plugins": [ "@babel/plugin-transform-modules-commonjs" // ESM→CJS ] }

2. TypeScript工程适配

TypeScript 4.7+原生支持ESM配置，关键tsconfig.json选项：

{ "compilerOptions": { "module": "NodeNext", // 或"ES2020" "moduleResolution": "NodeNext", "outDir": "./dist", "rootDir": "./src" }, "ts-node": { "esm": true, "experimentalSpecifierResolution": "node" } }

3. 构建工具链选择

不同构建工具对混合模块的支持差异：

常见陷阱与性能优化

1. 路径解析差异

ESM要求完整的文件扩展名，这与CommonJS的自动补全行为不同：

// CommonJS const utils = require('./utils') // 自动查找utils.js // ESM import utils from './utils.js' // 必须显式指定扩展名

2. 全局变量替代方案

传统Node.js全局变量在ESM中的替代方案：

实现示例：

import { fileURLToPath } from 'url' const __dirname = path.dirname(fileURLToPath(import.meta.url))

3. 循环引用处理

两种模块系统处理循环引用的方式截然不同：

• CommonJS：返回未完成的模块引用
• ESM：静态分析创建绑定，引用总是最新值

// ESM循环引用示例 // a.mjs import { b } from './b.mjs' export const a = 'value' // b.mjs import { a } from './a.mjs' console.log(a) // 能获取到最新值

4. 性能考量

混合环境下的模块加载性能对比：

企业级迁移路线图

阶段一：准备期（1-2周）

1. 代码静态分析：

   $ npx depcheck --json > dependencies.json $ npx eslint --rule 'no-require: error' src/

2. 建立代码规范：
   • 禁用require.extensions
   • 统一文件扩展名策略
   • 配置ESLint规则集

阶段二：并行运行（2-4周）

1. 双构建输出配置：

   { "scripts": { "build:cjs": "tsc --module commonjs --outDir dist/cjs", "build:esm": "tsc --module es2020 --outDir dist/esm" } }

2. 渐进式迁移策略：
   • 新功能严格使用ESM
   • 旧模块逐步重构
   • 关键路径性能测试

阶段三：完全迁移（1周）

1. 最终检查清单：

   • [ ] 所有测试通过
   • [ ] 性能基准达标
   • [ ] 文档更新完成
   • [ ] CI/CD流水线适配

2. 锁定模式配置：

   { "type": "module", "engines": { "node": ">=16.0.0" } }

模块化未来展望

Node.js核心团队正在推进的模块系统改进包括：

• 更完善的import.metaAPI
• WASM模块集成方案
• 模块注册表(Registry)标准
• 运行时模块热替换(HMR)

// 实验性功能示例 import module from 'node:module' const { createRequire } = module // 在ESM中创建require函数 const require = createRequire(import.meta.url) const legacy = require('./legacy.cjs')