JavaScript模块化演进：从CommonJS到ES Modules的最佳实践

JavaScript最初只作为网页端简单脚本语言设计，并不具备原生模块系统。随着前端应用规模急剧扩张以及Node.js在后端的普及，社区先后推出了CommonJS、AMD、CMD等方案，并最终由ECMAScript官方在ES6标准中确立了ES Modules规范。本文将剖析CommonJS与ES Modules的核心机制差异，厘清现代化项目迁移与混用互操作的关键步骤，并给出工程化落地的最佳实践方案。

一、JavaScript模块化演进脉络

在ES6规范发布前，模块封装经历了全局命名空间对象、立即执行函数（IIFE）、以及运行在Node.js中的CommonJS（CJS）等多个阶段。了解这些阶段的演变目标，有助于掌握现代构建工具与Node.js运行时的处理逻辑。

图 1：JavaScript 模块系统演进历程与核心驱动要素

二、CommonJS 与 ES Modules 的底层机制对比

虽然两者在代码书写上都遵循“导入”与“导出”的形式，但在底层执行机制上有本质的区别。这些差异直接决定了现代构建工具（如 Rollup、Vite、Webpack）在优化效率、Tree-shaking 和死代码消除方面的上限。

图 2：CommonJS 与 ES Modules 核心机制横向对比

1. 值拷贝 vs 动态只读引用 (Live Binding)

在CommonJS中，模块导出的是值的拷贝。一旦导出完成，模块内部对该变量的修改不会反馈到引用处：

// counter.cjs
let count = 1;
function increment() {
  count++;
}
module.exports = { count, increment };

// main.cjs
const { count, increment } = require('./counter.cjs');
console.log(count); // 输出: 1
increment();
console.log(count); // 输出仍为: 1 (导出的原始值已被快照复制)

而在ES Modules中，导出的并不是变量的值，而是对内存地址的动态只读引用（Live Binding）：

// counter.mjs
export let count = 1;
export function increment() {
  count++;
}

// main.mjs
import { count, increment } from './counter.mjs';
console.log(count); // 输出: 1
increment();
console.log(count); // 输出: 2 (随源模块动态变化，但当前文件不可直接写入 count = 3)

三、平滑迁移指南：从 CJS 到 ESM 的操作步骤

在现有Node.js与前端工程中从CommonJS全量或渐进迁移到ES Modules，推荐遵循以下标准化步骤，避免运行时抛出 ERR_REQUIRE_ESM 错误。

图 3：CommonJS 项目向 ES Modules 渐进式迁移四步法

步骤 1：明确模块系统边界

在 Node.js 中，默认的 .js 文件会被当做 CommonJS。若要在全局启用 ESM，需要在 package.json 中设置：

{
  "name": "my-modern-project",
  "version": "1.0.0",
  "type": "module"
}

声明后，所有 .js 文件均作为 ESM 运行。若项目中个别构建脚本仍需使用 CommonJS，可将其后缀显式重命名为 .cjs。

步骤 2：替代缺失的 Node.js 专用全局变量

在 ESM 环境中，__dirname、__filename 和 require 不再直接存在。需要通过 import.meta.url 重新计算路径：

import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

// 获取当前文件绝对路径与目录
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// 拼接本地资源路径
const configPath = join(__dirname, 'config.json');

四、混合生态中的双模块分发 (Dual-Package) 最佳实践

对于开源类库或组件库作者，当前社区仍处于 CJS 与 ESM 共存状态。为了保证不论用户使用 require() 还是 import 均能正常调用，必须在 package.json 中配置条件导出（Conditional Exports）。

{
  "name": "data-transformer",
  "version": "2.0.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./package.json": "./package.json"
  }
}

五、工程化选型与最佳实践总结

结合现代前端打包工具（Vite、Rollup、esbuild、Webpack 5）与服务端 Node.js 长期支持版（LTS），推荐在架构设计时遵循以下决策与规范：

图 4：不同业务场景下的模块化方案决策与选型矩阵

总结而言，ES Modules 不仅统一了前后端 JavaScript 的模块化规范，其静态化解析与只读引用特性更赋能了现代打包工具的高效优化。新项目应当全面拥抱 "type": "module"，而公共类库则应通过配置标准条件导出，以最小的维护成本完成生态的平滑演进。