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

从CommonJS到ES ModulesNode.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版本开始实验性支持ESM16版本后达到生产就绪状态。建议使用LTS版本并检查以下配置$ node --version # 需≥14.18.0或≥16.0.0 $ npm init -y # 确保package.json存在关键兼容性矩阵Node版本ESM支持度需要标志位12不支持N/A12-14实验性支持--experimental-modules≥15稳定支持无需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-resolutionnode 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. 构建工具链选择不同构建工具对混合模块的支持差异工具ESM支持度混合模式方案webpack5配置experiments.outputModulerollup原生支持使用rollup/plugin-commonjsesbuild原生支持自动转换CommonJSvite原生支持开发模式直接支持常见陷阱与性能优化1. 路径解析差异ESM要求完整的文件扩展名这与CommonJS的自动补全行为不同// CommonJS const utils require(./utils) // 自动查找utils.js // ESM import utils from ./utils.js // 必须显式指定扩展名2. 全局变量替代方案传统Node.js全局变量在ESM中的替代方案CommonJSESM替代方案__dirnameimport.meta.urlfileURLToPath__filenameimport.meta.urlrequire.mainimport.meta.main实现示例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. 性能考量混合环境下的模块加载性能对比操作CommonJSESM差异原因首次加载较慢快30%ESM预解析依赖重复加载快更快ESM缓存更高效动态导入N/A快50%原生Promise支持大型模块树内存高内存低ESM静态分析优化企业级迁移路线图阶段一准备期1-2周代码静态分析$ npx depcheck --json dependencies.json $ npx eslint --rule no-require: error src/建立代码规范禁用require.extensions统一文件扩展名策略配置ESLint规则集阶段二并行运行2-4周双构建输出配置{ scripts: { build:cjs: tsc --module commonjs --outDir dist/cjs, build:esm: tsc --module es2020 --outDir dist/esm } }渐进式迁移策略新功能严格使用ESM旧模块逐步重构关键路径性能测试阶段三完全迁移1周最终检查清单[ ] 所有测试通过[ ] 性能基准达标[ ] 文档更新完成[ ] CI/CD流水线适配锁定模式配置{ type: module, engines: { node: 16.0.0 } }模块化未来展望Node.js核心团队正在推进的模块系统改进包括更完善的import.metaAPIWASM模块集成方案模块注册表(Registry)标准运行时模块热替换(HMR)// 实验性功能示例 import module from node:module const { createRequire } module // 在ESM中创建require函数 const require createRequire(import.meta.url) const legacy require(./legacy.cjs)