企业官网建设流程全解析

Babel 的 AMD 模块转换插件 @babel/plugin-transform-modules-amd 完全指南：从 ES Modules 到 RequireJS 的编译实战

【免费下载链接】babel🐠 Babel is a compiler for writing next generation JavaScript.项目地址: https://gitcode.com/gh_mirrors/ba/babel

本文围绕 Babel 仓库中的 @babel/plugin-transform-modules-amd 官方文档与 源码实现 展开，系统讲解该插件如何将 ES2015 模块语法编译为 AMD（Asynchronous Module Definition）格式，覆盖安装配置、依赖图生成、导入导出重写、模块命名、Interop 策略、动态 import 支持等全部核心能力，并结合仓库内大量 fixtures 测试给出可直接对照的输入输出示例，帮助你在基于 RequireJS/AMD 加载器的传统前端工程中安全地使用现代 JavaScript 模块语法。

一、插件是什么：ES2015 模块 → AMD 的编译器

@babel/plugin-transform-modules-amd是 Babel 官方发布的模块转换插件之一，其 package.json 中的描述明确给出了定位：“This plugin transforms ES2015 modules to AMD”。它接受import/export等 ES 模块语法作为输入，将其重写为符合 AMD 规范的define(...)调用，从而让现代模块代码可以在 RequireJS、Dojo 等 AMD 加载器环境下运行。

插件位于仓库 packages/babel-plugin-transform-modules-amd 目录下，核心实现只有一个文件 src/index.ts，但它并非从零实现所有逻辑，而是复用了@babel/helper-module-transforms这一模块转换基础设施（在 package.json 中声明为依赖），因此它与 CJS、UMD、SystemJS 等兄弟插件共享同一套模块元数据归一化、Interop 包装与 live binding 重写逻辑，行为高度一致。

二、安装与基本用法

根据官方 README，可以通过 npm 或 yarn 安装为开发依赖：

npm install --save-dev @babel/plugin-transform-modules-amd

yarn add @babel/plugin-transform-modules-amd --dev

安装后在 Babel 配置中启用：

{ "plugins": ["@babel/plugin-transform-modules-amd"] }

从源码 src/index.ts 可以看到，插件注册的 visitor 名称为transform-modules-amd，并在pre()阶段向文件状态写入"@babel/plugin-transform-modules-*": "amd"，供同一次编译中的其他插件（例如动态 import 提案插件）查询当前采用的模块方案。

值得注意的是，该插件要求 Babel 核心版本为^7.0.0-0 || ^8.0.0（见 src/index.ts），即同时支持 Babel 7 与 Babel 8。

三、编译输出长什么样：依赖图与 define 包装

AMD 的核心是define(deps, factory)三段式结构：依赖数组 + 工厂函数。插件源码用两个模板声明了两种包装形态（src/index.ts）：

// 有名模块 / 普通模块 define(MODULE_NAME, AMD_ARGUMENTS, function(IMPORT_NAMES) { }) // 匿名模块（仅当文件中只有动态 import、没有静态模块语句时） define(["require"], function(REQUIRE) { })

以一个混合了各种导入导出形式的典型文件为例（来自测试 amd/overview/input.mjs）：

import "foo"; import "foo-bar"; import "./directory/foo-bar"; import foo from "foo"; import * as foo2 from "foo"; import {bar} from "foo"; import {foo as bar2} from "foo"; var test; export {test}; export var test2 = 5; export default test;

插件编译输出（amd/overview/output.js）：

define(["exports", "foo", "foo-bar", "./directory/foo-bar"], function (_exports, _foo, _fooBar, _fooBar2) { "use strict"; Object.defineProperty(_exports, "__esModule", { value: true }); _exports.test2 = _exports.test = _exports.default = void 0; _foo = babelHelpers.interopRequireWildcard(_foo); var foo2 = _foo; var test; var test2 = _exports.test2 = 5; var _default = _exports.default = test; _foo.default; foo2; _foo.bar; _foo.foo; });

这份输出清楚地展示了编译的全部关键动作：

• 依赖收集与去重：多个来源字符串（"foo"、"foo-bar"、"./directory/foo-bar"）按出现顺序依次进入 AMD 依赖数组；同源多次 import 被合并。
• 导入重写：每个依赖对应一个工厂函数参数（_foo、_fooBar……），源码中对导入标识符的引用被改写为对这些参数的属性访问（如bar→_foo.bar）。
• 导出对象注入：只要文件存在导出，就在依赖数组中注入"exports"字符串，并把_exports作为首个工厂参数。
• Interop 包装：命名空间导入与默认导入分别使用babelHelpers.interopRequireWildcard/babelHelpers.interopRequireDefault包装（详见下文第五节）。
• 导出初始化：通过Object.defineProperty(_exports, "__esModule", { value: true })打上 ES 模块标记，并将所有导出名先初始化为void 0，随后在各声明处同步赋值。

纯副作用导入（如import "./foo"）只把来源字符串放入依赖数组，不产生任何变量参数——见测试 amd/imports/input.mjs 与其输出 amd/imports/output.js：

define(["./foo", "./foo-bar", "./directory/foo-bar"], function (_foo, _fooBar, _fooBar2) { "use strict"; });

四、核心编译流程：源码级工作原理

结合 src/index.ts 的Program.exit处理器（L132-L221），AMD 转换的完整流水线如下：

1. 判断是否为模块：调用isModule(path)。若不是模块文件（无任何 import/export），则直接返回；仅当该文件此前注册过动态 import（requireId存在）时才注入匿名包装define(["require"], ...)。
2. 模块名解析：通过getModuleName(this.file.opts, options)计算模块名（依赖moduleIds/moduleId选项，详见第六节）。
3. 委托rewriteModuleStatementsAndPrepareHeader：这是@babel/helper-module-transforms提供的核心入口（src/index.ts），一次性完成模块元数据归一化、顶层this重写、live binding 重写与严格模式指令注入。其内部行为受传入选项控制：
   • !allowTopLevelThis时执行rewriteThis，把模块顶层的this替换为undefined；
   • strictMode !== false时自动注入"use strict"指令；
   • 根据importInterop校验并确定每种导入的 interop 策略（合法值校验见 normalize-and-load-metadata.ts）。
4. 组装 AMD 依赖数组与工厂参数：按顺序依次放入"exports"（如有导出）、各个模块来源字符串，并生成对应的工厂参数标识符。
5. 生成导出初始化语句：buildNamespaceInitStatements负责为每个导入来源生成命名空间初始化代码（如export * from的 re-export 展开）。
6. 头部语句提升与包装注入：ensureStatementsHoisted(headers)确保头部语句置顶，最后调用injectWrapper把整个程序体塞进define(...)工厂函数中。

injectWrapper（src/index.ts）的实现值得注意：它先清空Program的 body 与 directives，再把预构造的define(...)语句 push 进 body，随后把原来的指令（如"use strict"）和语句整体搬入工厂函数体内——这就是为什么转换结果总是“程序内容完整包进 define、保持原有顺序”的结构。

五、导入导出的完整重写规则

5.1 默认导入：interopRequireDefault

测试 amd/imports-default/input.mjs：

import foo from "foo"; import {default as foo2} from "foo";

输出 amd/imports-default/output.js：

define(["foo"], function (_foo) { "use strict"; _foo = babelHelpers.interopRequireDefault(_foo); _foo.default; _foo.default; });

默认导入经过interopRequireDefault包装后，所有对默认导出的引用都改写为对.default属性的访问。

5.2 命名导入：属性访问改写

测试 amd/imports-named/input.mjs 中多个来源的命名导入（含重命名）会被统一改写为属性访问，如bar2→_foo.bar2、baz2→_foo.bar，见 amd/imports-named/output.js。

5.3 默认 + 命名混合导入

测试 amd/imports-mixing/input.mjs：

import foo, {baz as xyz} from "foo";

输出 amd/imports-mixing/output.js 中整个模块被interopRequireWildcard包装，foo→_foo.default，xyz→_foo.baz。命名空间导入import * as foo同样走 wildcard 包装（见 amd/imports-glob）。

5.4 导出：声明、默认导出与 live binding 保持

变量/函数/类导出（amd/exports-variable/input.mjs）展示了各类声明导出的处理：导出名被收集进_exports.foo7 = ... = void 0的初始化链，随后每个声明处同步赋值（如var foo = _exports.foo = 1），函数与类则通过_exports.foo8 = foo8;的延迟赋值保持语义（见 amd/exports-variable/output.js）。

默认导出（amd/export-default/input.mjs）的export default 42被编译为var _default = _exports.default = 42;（见 amd/export-default/output.js）。

关键能力：live binding（实时绑定）保持。ES 模块的导出是“活绑定”，模块内部对导出变量的赋值必须同步反映到外部。测试 amd/remap/input.mjs 中的自增、重赋值、别名导出、一变量多别名等场景，在输出 amd/remap/output.js 中被精确改写：

_exports.test = _exports.f = _exports.e = _exports.c = _exports.a = void 0; var test = _exports.test = 2; _exports.test = test = 5; _test = test++, _exports.test = test, _test;

test++被展开为“先保存旧值、自增、再同步导出”的复合表达式，函数作用域内的同名var test则被识别为局部变量而不触碰导出，保证了作用域隔离下的语义精确性。

5.5 再导出：export from 与 export * from

命名再导出export { foo } from "foo"会被编译为对来源模块的重新导出语句。通配再导出（amd/export-from/input.mjs 中的export * from "foo"）在输出 amd/export-from/output.js 中展开为对_foo键的遍历复制，通过 getter 实现惰性取值，并跳过default与__esModule两个特殊键：

Object.keys(_foo).forEach(function (key) { if (key === "default" || key === "__esModule") return; if (key in _exports && _exports[key] === _foo[key]) return; Object.defineProperty(_exports, key, { enumerable: true, get: function () { return _foo[key]; } }); });

5.6 函数导出的提升

测试 amd/hoist-function-exports 展示了export function nextOdd(n)被提升至工厂函数顶部并先行赋值_exports.nextOdd = nextOdd，而 IIFE 赋值的isOdd保持在原位置，输出见 amd/hoist-function-exports/output.js。同时可见对导入函数isEven的调用被改写为(0, _evens.isEven)(n)，以保证this不被隐式传入——这是模块转换中处理导入函数调用的标准手法。

5.7 导入顺序保持

ES 模块的副作用导入必须保持书写顺序。测试 amd/import-order 验证了插件按源码顺序生成依赖数组["./foo", "./bar", "./derp", "./qux"]，即使中间混有带绑定的导入也不改变相对顺序（见 amd/import-order/output.js）。

六、模块命名：moduleIds 与 moduleId

AMD 的define第一个参数可以是模块名。插件通过getModuleName（来自 helper-module-transforms）解析文件名或显式配置来生成。

测试 amd/module-name 展示了仅开启moduleIds: true时，以文件路径派生的模块名：

{ "sourceType": "module", "plugins": [["transform-modules-amd", { "moduleIds": true }]] }

输出 amd/module-name/output.js：

define("amd/module-name/input", [], function () { "use strict"; foobar(); });

测试 amd/get-module-name-option 展示了显式指定moduleId的用法：

{ "sourceType": "module", "plugins": [["transform-modules-amd", { "moduleIds": true, "moduleId": "my custom module name" }]] }

其输出 amd/get-module-name-option/output.js 为：

define("my custom module name", [], function () { "use strict"; });

在源码层面，模块名通过 src/index.ts 生成：getModuleName(this.file.opts, options)有值则转成字符串字面量并作为define的首参；否则MODULE_NAME为空，插件生成匿名 define（define(deps, factory)两参形式），由 AMD 加载器按脚本路径自动命名。

七、配置选项全解

插件暴露的选项接口定义在 src/index.ts，全部选项如下：

7.1 noInterop：跳过 interop 包装

测试 amd/noInterop-import-default-only/options.json 使用{ "noInterop": true }时，默认导入不再经过interopRequireDefault，直接访问_foo.default（见 amd/noInterop-import-default-only/output.js）。这适用于你确认所有依赖均为真正的 ES 模块、无需兼容 CJS 的环境。

7.2 importInterop：精细控制 interop 粒度

importInterop: "node"模拟 Node.js 的 ESM-CJS 互操作规则。测试 importInterop-node/import-default/input.mjs 的默认导入在"node"模式下直接调用_foo()而无需.default包装（见 importInterop-node/import-default/output.js）。仓库中还有完整的importInterop-node与importInterop-nonefixtures 目录，分别覆盖 default、named、wildcard、named-and-default、export-from 等全部形态。

7.3 strict 与 strictMode

• strict: true时，helper 的rewriteModuleStatementsAndPrepareHeader将跳过__esModule头与导出名列表声明（helper index.ts），适合输出本身被其他机制保证严格模块语义的场景。
• strictMode: false时跳过"use strict"注入（helper index.ts）。

7.4 loose 的废弃与 assumptions 迁移

源码 src/index.ts 明确处理了loose的废弃：一旦检测到loose选项存在，插件会输出console.warn，提示改用constantReexports与enumerableModuleMeta两个 assumptions；同时内部将constantReexports与enumerableModuleMeta分别解析为api.assumption(...) ?? options.loose。仓库中 loose（{ "loose": true }）、assumption-constantReexports、assumption-enumerableModuleMeta 三套 fixtures 并行存在，便于对比迁移前后的输出差异。

八、动态 import() 的 AMD 化

插件对import()动态导入提供了原生支持。源码中注册了"CallExpression|ImportExpression"visitor（src/index.ts）：当文件中存在动态 import（需与@babel/plugin-proposal-dynamic-import配合触发），插件会生成requireId、resolveId、rejectId三个唯一标识符，并把import("foo")重写为基于 AMD 依赖注入的 Promise：

new Promise((resolve, reject) => require(["foo"], imported => resolve(imported), reject) )

关键细节：由于 AMD 的require只能在工厂函数内以依赖形式注入，动态 import 的存在会强制插件在依赖数组中追加"require"字符串及其工厂参数（src/index.ts）；若文件没有静态模块语句，则退化为第二节所述的匿名包装define(["require"], ...)。仓库在 regression 目录下保留了 4192、9346 等回归测试用于守护该行为。

九、与 preset-env 的集成

无需手动逐个引入插件。@babel/preset-env将 AMD 作为可选的模块输出方案，模块转换映射定义在 module-transformations.ts：

amd: "transform-modules-amd",

当@babel/preset-env配置"modules": "amd"时，preset 会从 available-plugins.ts 中按需加载本插件并启用，从而把 AMD 编译能力接入现代浏览器 target 驱动的自动化流程。

十、测试体系与验证方式

该插件拥有完整的 fixture 测试体系，位于 test/fixtures 目录，按amd（默认）、loose、assumption-*、importInterop-*、interop-module-string-names、misc、regression等维度组织，每个用例由input.mjs（或input.js）+options.json+output.js三元组构成，可当作编译行为的“活文档”：想确认某个语法在某种配置下的输出，直接对照对应 fixtures 即可。

其中interop-module-string-names与interop-module-string-names-loose两组用例专门覆盖字符串形式的模块名导出（如export { "str" as "str2" } from "foo"），misc/local-exports-var-declarations覆盖局部导出变量的声明场景。测试运行器为@babel/helper-plugin-test-runner（见 package.json），在仓库根目录执行make test或对应 jest 命令即可运行全部用例。

十一、适用场景与限制

适用场景：遗留系统基于 RequireJS/AMD 加载器、但希望用 ES 模块语法编写新代码；或者需要把 ES 模块产物交给按 AMD 规范打包的构建链路（如部分 r.js 优化管线）。它与同仓库的 CJS、UMD、SystemJS 转换插件共享设计理念，迁移到其他模块方案时输出结构高度可预期。

限制与注意点：

• 输出依赖 Babel helpers（如interopRequireDefault、interopRequireWildcard），需要配合@babel/plugin-transform-runtime或@babel/plugin-external-helpers注入 helpers；从输出可以看出，所有 interop 调用均以babelHelpers.*形式引用。
• 转换产物面向 AMD 加载器运行时，不适用于 Node.js 原生 ESM/CJS 直接加载。
• loose已废弃，新项目应直接使用constantReexports/enumerableModuleMetaassumptions。
• 插件只负责模块语法的重写，JSX、TypeScript、装饰器等语言特性需要搭配相应插件或 preset 一并配置。

【免费下载链接】babel🐠 Babel is a compiler for writing next generation JavaScript.项目地址: https://gitcode.com/gh_mirrors/ba/babel