浏览器中ESM与AMD模块共存的解决方案

一、引言

JavaScript模块化的历史，本质上是一场"分久必合"的演进。从最初用IIFE（立即执行函数）解决全局污染，到RequireJS带来AMD（异步模块定义）规范，让浏览器端实现异步加载，再到Node.js普及CommonJS，最后ES6在语言标准层面统一了模块规范------每一步都是为了解决特定场景下的痛点。

然而现实中，模块规范的"战国时代"并未真正结束。许多大型项目经过多年迭代，代码库中既有老旧的AMD模块，也有新写的ESM模块。更常见的是，团队希望复用某个只提供了AMD格式的第三方库，同时用ESM编写新功能。浏览器中ESM与AMD模块如何共存，成了一个绕不开的工程问题。

本文将从问题根源出发，系统梳理浏览器端ESM与AMD共存的四种主流方案，并给出实际应用建议。

二、问题根源：两种规范的设计差异

2.1 AMD：异步优先，加载器驱动

AMD（Asynchronous Module Definition）是专为浏览器设计的模块规范。其核心思想是异步加载------模块的加载不影响后面语句的执行，所有依赖都定义在回调函数中，等加载完成后再执行。

典型AMD代码（使用RequireJS）：

javascript 复制代码

define(['moduleA', 'moduleB'], function(a, b) {
    // 模块代码
    return { /* exports */ };
});

2.2 ESM：原生标准，编译时解析

ES Module（ESM）是ECMAScript官方标准，在语言层面实现了模块功能。它使用import和export语法，支持编译时静态分析，被现代浏览器原生支持。

典型ESM代码：

javascript 复制代码

import { foo } from './moduleA.js';
export const bar = 'hello';

2.3 冲突的核心

两种规范的核心差异在于：

加载机制：AMD依赖运行时加载器（如RequireJS），ESM依赖浏览器原生支持
语法体系 ：AMD使用define/require函数调用，ESM使用import/export关键字
依赖解析：AMD动态解析，ESM静态解析

当同一个页面或同一个项目中同时存在两种格式的模块时，就需要一套桥梁机制让它们互相识别和调用。

三、解决方案全景

根据实际场景的不同，浏览器中ESM与AMD共存有四种主流方案：

方案	适用场景	核心思路
构建时转换	新项目、可全量构建	将AMD统一转换为ESM
Babel运行时转换	复杂混合项目	在浏览器端实时转译ESM为AMD
RequireJS插件加载	以AMD为主的项目	用插件按需加载ESM模块
轻量级AMD加载器	自动化转换项目	用微型加载器模拟ESM行为

四、方案一：构建时统一转换（推荐）

4.1 核心思路

在构建阶段将所有模块统一为一种格式，是最干净、最彻底的解决方案。现代构建工具（Webpack、Vite、Rollup）都原生支持同时处理ESM、CommonJS和AMD模块。

4.2 具体做法

使用Webpack/Vite/Rollup ：这些工具内部会将所有模块格式统一转换为目标格式。配置得当后，源码中无论是import还是define，最终都能打包成统一的ESM或UMD产物。

使用tsup等库打包工具：在库开发场景中，tsup可以同时输出ESM、CJS和类型声明等多种格式，让使用者根据自己的环境选择合适格式。

4.3 优势与局限

优势：无运行时开销、代码纯净、维护简单
局限：需要完整的构建流程，不适合无法改造的存量系统

五、方案二：Babel插件实时转换

5.1 核心思路

在浏览器端使用Babel实时将ESM代码转译为AMD格式，让RequireJS能够加载和执行。

5.2 关键工具：babel-plugin-transform-modules-requirejs-babel

这是一个专门解决ESM与AMD混合场景的Babel插件。与官方@babel/plugin-transform-modules-amd相比，它支持更复杂的场景：

任意依赖级别的混合：支持ESM和AMD模块在任何依赖层级上混合使用
默认导出兼容 ：如果ESM模块只有一个默认导出，会直接导出而不包装成{ default: ... }，保持兼容性
识别AMD bundles ：能识别包含多个define语句的AMD模块包

5.3 配置示例

javascript 复制代码

// Babel配置
{
  plugins: [
    'transform-modules-requirejs-babel'
  ]
}

如需自定义模块路径解析：

javascript 复制代码

{
  plugins: [
    ['transform-modules-requirejs-babel', {
      resolvePath: function(sourcePath, currentFile, opts) {
        // 自定义路径转换逻辑
        if (sourcePath.indexOf('!') < 0 && 
            sourcePath !== 'require' && 
            sourcePath !== 'module' && 
            sourcePath !== 'exports') {
          return 'es6!' + sourcePath;
        }
      }
    }]
  ]
}

5.4 优势与局限

优势：支持复杂的混合依赖、可随时在ESM和AMD之间互转
局限：需要Babel运行时环境，有一定性能开销

六、方案三：RequireJS ESM插件按需加载

6.1 核心思路

通过RequireJS插件机制，在define或require中通过特殊前缀（如esm!）加载ESM模块。

6.2 关键工具：requirejs-esm

requirejs-esm是一个RequireJS插件，专门将ESM模块转换为AMD格式供RequireJS使用。

与Babel方案的区别在于：它只转换模块格式，不转译语言特性 ，因此速度更快。如果需要将代码转译为更早的ECMAScript版本，则需要配合requirejs-babel7使用。

6.3 配置与使用

安装：

bash 复制代码

npm install requirejs-esm --save-dev

RequireJS配置：

javascript 复制代码

requirejs.config({
  paths: {
    esm: 'node_modules/requirejs-esm/dist/plugin'
  }
});

使用ESM模块：

javascript 复制代码

define(['esm!your-esm-module'], function(module) {
  // 使用ESM模块
});

ESM模块内部的import语句会被自动处理。如果检测到源文件已经包含define、require或require.config调用，插件会原样返回，不做转换。

6.4 优化器注意事项

如果使用RequireJS优化器r.js，需要在构建配置中移除插件的编译功能：

javascript 复制代码

// r.js构建配置
pragmaOnSave: {
  excludeEsm: true  // 移除esm.js中的转译代码
}

6.5 优势与局限

优势：轻量、快速、与现有RequireJS项目无缝集成
局限：RequireJS官方优化器r.js不支持source map，需使用@prantlf/requirejs分支

七、方案四：轻量级AMD加载器

7.1 核心思路

对于只需要加载AMD模块、不需要RequireJS全部功能的场景，可以使用更轻量的加载器。

7.2 关键工具：@polymer/esm-amd-loader

这是一个仅有1.4KB的微型AMD加载器，主要用于自动化项目转换场景。

Polymer CLI 1.7.0及以上版本会自动使用Babel AMD转换插件将项目转换为AMD模块，并自动注入此加载器到HTML中。

7.3 使用示例

html 复制代码

<!-- 引入加载器 -->
<script src="./node_modules/@polymer/esm-amd-loader/lib/esm-amd-loader.min.js"></script>

<script>
  define(['./foo.js'], function(foo) {
    console.log('imported', foo.stuff, 'from foo.js');
  });
</script>

模块定义：

javascript 复制代码

// foo.js
define(['exports', 'require', 'meta'], function(exports, require, meta) {
  exports.stuff = 'neat stuff';
  
  // 动态加载依赖
  require(['../bar.js'], function(bar) {
    console.log(meta.url, 'dynamically loaded bar.js:', bar);
  });
});

7.4 与RequireJS的差异

体积更小：1.4KB vs RequireJS的6.6KB
只支持路径形式的依赖，不支持显式命名模块
没有全局require函数，用define定义的模块立即执行

7.5 优势与局限

优势：极致轻量、适合自动化转换场景
局限：功能有限，不适合复杂手动编码场景

八、补充方案：UMD------模块格式的"万金油"

除了上述方案，还有一种从模块产出端解决问题的思路------UMD（Universal Module Definition）。

UMD本质上是一个模块格式包装器，会在启动时检测当前环境支持哪种模块系统，然后进行适配：

javascript 复制代码

(function (root, factory) {
  if (typeof define === 'function' && define.amd) {
    // AMD环境
    define(['moduleB'], factory);
  } else if (typeof module === 'object' && module.exports) {
    // CommonJS/Node环境
    module.exports = factory(require('moduleB'));
  } else {
    // 浏览器全局变量
    root.returnExports = factory(root.moduleB);
  }
})(this, function (moduleB) {
  return {};
});

UMD的适用场景是库作者 ------发布一个UMD格式的包，使用者无论在AMD、CommonJS还是浏览器全局环境下都能直接使用。但它不适合解决已有代码库内部ESM与AMD混用的问题。

九、方案选型建议

场景	推荐方案	理由
新项目，可全量构建	方案一：构建时统一转换	最干净，无运行时开销
存量AMD项目，渐进式引入ESM	方案三：requirejs-esm	与RequireJS无缝集成，按需加载
复杂混合项目，需要深度互操作	方案二：Babel插件转换	支持任意依赖级别的混合
自动化转换项目（如Polymer）	方案四：轻量级加载器	体积小，自动化程度高
作为库作者发布包	UMD格式输出	一次构建，到处运行

十、总结

浏览器中ESM与AMD模块共存，本质上是在新旧技术栈过渡期的必然产物。ES6模块规范虽然"全方位简化了之前出现的模块加载器"，但现实世界的代码库不可能在一夜之间完成迁移。

本文介绍的四种方案各有侧重：

构建时转换是长期最优解
Babel实时转换适合复杂混合场景
RequireJS插件是与现有生态集成最平滑的方式
轻量级加载器是自动化场景下的高效选择

在实际项目中，建议优先评估能否通过构建工具统一模块格式------这是最彻底、最省心的方式。如果确实需要运行时共存，再根据项目现有的技术栈（是否已使用RequireJS、是否有Babel环境等）选择合适的方案。

正如一位开发者所说："ES6模块系统是集AMD和CommonJS之大成者。"理解这些过渡方案，不是为了永远停留在混合状态，而是为了更平稳地走向统一的ESM未来。