企业官网建设流程全解析

Babel 的 UMD 模块转换插件 @babel/plugin-transform-modules-umd：原理、配置与实战指南

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

@babel/plugin-transform-modules-umd 是 Babel 官方提供的 ES2015（ES Modules）→ UMD（Universal Module Definition）转换插件，它将import/export语法编译为同时兼容 AMD（RequireJS）、CommonJS 与浏览器全局变量三种加载环境的包装代码，是构建可分发到任意环境（Node、浏览器、AMD 加载器）的库文件的常用方案。本文基于当前仓库（Babel monorepo）中该插件的 README、核心实现 与 测试 fixtures 展开，带你掌握插件的安装方式、全部配置项、生成代码结构、浏览器全局名解析规则，以及如何结合源码理解其底层实现。

插件定位与适用场景

UMD 是一种同时兼容多种模块系统的包装模式：检测到 AMD 加载器（define.amd）时走 AMD 分支，检测到 CommonJS（exports/require）时走 CJS 分支，两者都不存在时则将模块导出挂载到全局对象上。插件@babel/plugin-transform-modules-umd的作用，就是把你用 ES Modules 编写的源码，整体包进这样一个可移植的 UMD 外壳中。

典型适用场景包括：

• 发布需要在 Node（CommonJS）、浏览器<script>直接引入、以及 AMD 加载器下都能运行的 JavaScript 库；
• 打包工具之外的“零构建”分发需求，例如直接通过script标签引入的 CDN 版本；
• 需要自定义浏览器端全局变量名（global.foo、global.foo.bar这种嵌套命名空间）的库。

在 Babel 插件家族中，它与 @babel/plugin-transform-modules-amd、@babel/plugin-transform-modules-commonjs 属于同一“模块转换”系列，区别仅在于目标模块系统的不同。

安装

该插件的官方文档给出了 npm 与 yarn 两种安装方式：

# npm npm install --save-dev @babel/plugin-transform-modules-umd # 或 yarn yarn add @babel/plugin-transform-modules-umd --dev

从仓库内的 package.json 可以看到，它的运行时依赖只有两个内部包：@babel/helper-module-transforms（模块语句改写与 interop 包装的核心工具）与@babel/helper-plugin-utils（插件声明辅助），并以@babel/core作为 peerDependency（当前版本为^8.0.0）。也就是说，使用前请确保你的项目中已安装对应版本的@babel/core。

基础用法：接入 Babel 配置

在.babelrc或babel.config.js中注册插件：

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

也可以按需传入配置对象：

{ "plugins": [ [ "@babel/plugin-transform-modules-umd", { "moduleId": "MyLib", "globals": { "react": "React" }, "exactGlobals": true } ] ] }

仓库测试目录test/fixtures/下的每个用例都由options.json（插件配置）、input.mjs（输入源码）与output.js（期望输出）组成，例如 fixtures/umd/module-id/options.json 展示了moduleId的配置方式。这些 fixtures 既是回归测试，也是理解每个选项行为的最直观示例。

完整选项说明

结合 src/index.ts 中声明的Options接口，插件支持以下选项：

注意：loose选项在源码中已标记为废弃（@deprecated），且会在使用时向控制台输出警告，提示改用constantReexports与enumerableModuleMetaassumptions（见 src/index.ts）。从实现看，constantReexports = api.assumption("constantReexports") ?? options.loose、enumerableModuleMeta = api.assumption("enumerableModuleMeta") ?? options.loose，即旧配置仍被兼容，但推荐迁移到 assumptions。

globals与exactGlobals：浏览器全局名映射

这是 UMD 插件区别于其他模块插件最核心的配置。它决定在浏览器（无 AMD、无 CommonJS）分支中，各依赖从哪个全局对象上读取。

• exactGlobals: false（默认）：globals映射的 key 使用导入路径去除扩展名后的“basename”，且映射值只作为全局成员名（不做点分展开）。例如测试 fixtures/umd/imports-exact-globals-false 中，import fooBar1 from "foo-bar"在浏览器分支对应global.foo-bar经标识符规范化后的global.fooBar。
• exactGlobals: true：globals映射的 key 使用完整导入路径（如"./mylib/foo-bar"、"fizzbuzz"），值支持点分嵌套命名空间。测试 fixtures/umd/imports-exact-globals-true-with-overrides 的配置为：

{ "plugins": [ [ "transform-modules-umd", { "globals": { "foo-bar": "fooBAR", "./mylib/foo-bar": "mylib.fooBar", "fizzbuzz": "fizz.buzz" }, "exactGlobals": true } ] ] }

对应浏览器分支输出为：

factory(global.fooBAR, global.mylib.fooBar, global.fizz.buzz);

注意global.fizz.buzz这种嵌套形式：底层实现buildBrowserArg会把点分字符串逐步 reduce 成成员表达式，并在 UMD 初始化时通过GLOBAL_REFERENCE = GLOBAL_REFERENCE || {}模板（buildPrerequisiteAssignment，见 src/index.ts）预创建global.mylib、global.fizz等中间对象，避免因中间命名空间不存在而抛错。

moduleId/moduleIds：模块名与浏览器全局名

moduleId同时决定两处：AMD 分支的define("MyLib", [...], factory)中的模块 ID，以及浏览器分支最终挂载的全局变量名global.MyLib = mod.exports。测试 fixtures/umd/module-id 的输出即为：

define("MyLib", [], factory); ... global.MyLib = mod.exports;

当未指定moduleId时，浏览器全局名默认取自文件名：basename(filename, extname(filename))再经toIdentifier规范化（src/index.ts）。例如测试 fixtures/umd/module-name（配置moduleIds: true）中，输入文件路径为umd/module-name/input.js，输出全局名为global.umdModuleNameInput，AMD ID 为"umd/module-name/input"。

生成的 UMD 代码结构解析

以插件测试中最完整的示例 fixtures/umd/overview 为例。输入是一段包含副作用导入、默认导入、命名空间导入、命名导入、re-export 与默认导出的典型模块：

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;

转换后输出如下（已按仓库 fixture 的原始输出整理）：

(function (global, factory) { if (typeof define === "function" && define.amd) { define(["exports", "foo", "foo-bar", "./directory/foo-bar"], factory); } else if (typeof exports !== "undefined") { factory(exports, require("foo"), require("foo-bar"), require("./directory/foo-bar")); } else { var mod = { exports: {} }; factory(mod.exports, global.foo, global.fooBar, global.fooBar); global.input = mod.exports; } })(typeof globalThis !== "undefined" ? globalThis : typeof self !== "undefined" ? self : this, 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.bar; _foo.foo; });

这段代码完整展示了 UMD 模式的三大分支与若干细节：

• AMD 分支：typeof define === "function" && define.amd时调用define(模块ID, [依赖数组], factory)，依赖数组包含"exports"及所有导入路径。
• CommonJS 分支：typeof exports !== "undefined"时调用factory(exports, require(...), ...)。
• 浏览器分支：创建mod = { exports: {} }，调用factory(mod.exports, global.foo, global.fooBar, ...)，最后global.input = mod.exports把模块导出挂到全局（input来自文件名）。
• 全局对象选取：按globalThis→self→this的优先级解析（对应 src/index.ts 中的typeof globalThis !== "undefined" ? globalThis : typeof self !== "undefined" ? self : this）。
• 模块体内重写：所有export被改写成对_exports的属性赋值；import * as foo2 from "foo"在默认（非 loose）模式下需要interopRequireWildcard包装；顶层"use strict"指令被移入工厂函数体内。
• 导出声明：__esModule标记、export default/ 命名导出的预声明（_exports.test2 = _exports.test = _exports.default = void 0）一应俱全。

源码中的装配流程

从 src/index.ts 可以看到插件在Program.exit阶段完成整个装配：

1. isModule(path)判断文件是否含import/export，否则直接跳过；
2. getModuleName(this.file.opts, options)解析moduleId；
3. rewriteModuleStatementsAndPrepareHeader调用@babel/helper-module-transforms完成模块语句改写，得到meta与头部声明；
4. 依据meta.source逐依赖构造三个参数数组：AMD 分支用路径字符串、CommonJS 分支用require(path)、浏览器分支用buildBrowserArg生成的全局成员表达式；
5. buildWrapper模板（src/index.ts）生成整个 UMD IIFE，最后把原body与指令塞进工厂函数体。

这种“改写模块语句 + 套壳 IIFE”的模式与 @babel/plugin-transform-modules-amd 同源，差异集中在浏览器分支的全局名解析逻辑（buildBrowserArg/buildBrowserInit）。

常用场景速查

• 仅需“双模式”运行（Node + AMD）：保持默认exactGlobals: false，浏览器分支会自动按导入路径的 basename 生成global.<Name>。
• 库需要自定义全局命名空间：设置exactGlobals: true与globals映射，支持"pkg/sub": "MyNS.Sub"这种点分嵌套。
• 固定导出名：使用moduleId: "MyLib"，浏览器端通过window.MyLib访问库 API。
• 第三方依赖的浏览器全局名：例如把"react"映射为"React"、把"lodash"映射为"_"，确保浏览器分支从正确全局读取依赖，而非生成错误的global.react。
• 与其他 Babel 插件组合：UMD 插件只处理模块语法，JSX、TypeScript、class 属性等语法转换仍需配合对应插件（如 @babel/preset-env、babel-plugin-transform-react-jsx）按需组合。

在仓库中继续深入

• 插件唯一入口与全部实现：packages/babel-plugin-transform-modules-umd/src/index.ts
• 模块语句改写与 interop 的底层工具：packages/babel-helper-module-transforms/src
• 完整测试夹具（每个选项都有对应输入/输出对）：packages/babel-plugin-transform-modules-umd/test/fixtures
• 测试运行器（如何执行这些 fixture 断言）：packages/babel-helper-plugin-test-runner/src

其中test/fixtures/umd/下的imports-exact-globals-*、module-id*、module-name*、override-import-name、override-export-name、remap、hoist-function-exports等用例，几乎覆盖了生产环境可能遇到的所有模块形态，是阅读源码时最好的对照材料。

结语

@babel/plugin-transform-modules-umd 的核心价值在于“一次编译、处处运行”：通过一个精心设计的 UMD IIFE 外壳，让 ES Modules 源码同时适配 AMD、CommonJS 与浏览器全局三种环境。掌握globals/exactGlobals的全局名解析规则、moduleId对输出命名的影响，以及 UMD 包装的生成流程，你就能在构建跨环境 JavaScript 库时游刃有余；而仓库中 src/index.ts 与成体系的 fixtures 测试，则是理解其内部实现的最佳教材。

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