antd-mobile 预构建产物(Pre-Built Bundles)全解析:UMD/CJS/ES 全格式、CDN 引入与兼容性选择

原创2026-09-22 15:53:391,699 阅读
文章标签:UI组件前端移动开发

antd-mobile 预构建产物(Pre-Built Bundles)全解析:UMD/CJS/ES 全格式、CDN 引入与兼容性选择

本篇指南以 antd-mobile 官方文档 docs/guide/pre-built-bundles.en.md 为骨架,系统梳理 bundle 目录下预构建产物的完整清单、开发版与生产版的区别、两份 UMD 文件的兼容性差异,以及 JS 与 CSS 的正确组合引入方式。读完本文,你将能在不借助任何打包工具的情况下,通过 <script>/<link> 或 CDN 直接接入 antd-mobile,并依据目标浏览器环境选择最合适的产物版本。

一、什么是预构建产物:bundle 目录的两大组成部分

antd-mobile 在发布时提供了一套预构建(pre-built)产物,它们与源码级别的 npm 包(es/、cjs/ 模块)不同,是已经完成编译、打包、压缩的整包文件,可以直接被浏览器、CDN 或非打包工具环境使用。这套产物分为两部分:

  • JS 资源:覆盖 cjs、es、umd 三种模块格式,每种格式又区分开发版与生产版;
  • CSS 资源:包含全量样式 style.css 与面向低版本浏览器的补丁样式 css-vars-patch.css。

其中 UMD 产物可以直接通过 <script> 标签加载并挂载为全局变量,是"无需构建工具、开箱即用"的核心形态。

二、JS 资源:development 与 production 双版本

2.1 开发版(仅用于开发环境)

以下产物带有 .development 后缀,只适合开发调试,不适合用于生产环境:

/bundle/antd-mobile.cjs.development.js
/bundle/antd-mobile.es.development.js
/bundle/antd-mobile.umd.development.js

2.2 生产版(压缩优化后可用于生产)

压缩并优化后的生产产物如下:

/bundle/antd-mobile.cjs.js
/bundle/antd-mobile.es.js
/bundle/antd-mobile.umd.js
/bundle/antd-mobile.compatible.umd.js

2.3 命名规则的源码印证

这份命名清单并非随意约定,而是由构建脚本直接生成的。在仓库根目录的 gulpfile.js 中,getViteConfigForPackage 通过 vite 的 lib 模式构建三份格式产物:

fileName: format => `${name}.${format}${isProd ? '' : `.${env}`}.js`,

其中 name 取自 package.json 的 "name": "antd-mobile",env 遍历 development 与 production(见 buildBundles)。因此展开后恰好得到:

环境 文件名 说明
development antd-mobile.cjs.development.js CommonJS 格式,未压缩
development antd-mobile.es.development.js ES Module 格式,未压缩
development antd-mobile.umd.development.js UMD 格式,未压缩
production antd-mobile.cjs.js CommonJS 格式,esbuild 压缩
production antd-mobile.es.js ES Module 格式,esbuild 压缩
production antd-mobile.umd.js UMD 格式,esbuild 压缩
production antd-mobile.compatible.umd.js 兼容版 UMD,webpack + Babel 构建

构建配置中 minify: isProd ? 'esbuild' : false(gulpfile.js)进一步印证:.development 产物未做压缩,仅用于开发排错。

顺带一提,仓库在 package.json 中通过 size-limit 对 ./lib/bundle/antd-mobile.es.js 设置了 200 kB 的体积上限,说明这份 ES 生产包是体积控制的核心基准。

三、UMD 双版本:antd-mobile.umd.js 与 antd-mobile.compatible.umd.js

两份 UMD 文件是预构建产物中最容易混淆的部分,它们的本质区别在于是否经过 Babel 转译,进而决定了浏览器兼容性:

产物 是否经 Babel 处理 兼容性
antd-mobile.umd.js 否 Chrome >= 61、iOS >= 11
antd-mobile.compatible.umd.js 是 Chrome >= 49、iOS >= 9

3.1 兼容版是如何构建出来的

从构建脚本可以完整还原 compatible 版的生产链路。umdWebpack(gulpfile.js)以 lib/es/index.js 为入口执行 webpack 打包,并在 babel-loader 中通过 @babel/preset-env 指定转译目标:

'targets': {
  'chrome': '49',
  'ios': '9',
},

随后 copyUmd(gulpfile.js)把 webpack 输出的 lib/umd/antd-mobile.js 重命名为 antd-mobile.compatible.umd.js 并复制进 lib/bundle/。这与文档声明的 Chrome >= 49、iOS >= 9 完全一致。

3.2 标准版的兼容边界

标准版 antd-mobile.umd.js 由 vite 构建(cssTarget: 'chrome61',见 gulpfile.js),未经过 Babel 转译,因此只保证 Chrome >= 61、iOS >= 11。如果你的用户群停留在较老的内核(例如 iOS 9~10 的 WebView),应选择 compatible 版。

3.3 全局变量与外部依赖

两份 UMD 都遵循相同的约定:

  • 通过 library: { name: 'antdMobile' } 将组件库挂载为全局变量 window.antdMobile(UMD 构建见 gulpfile.js,vite 构建见 gulpfile.js);
  • react 与 react-dom 被声明为 external,需要在使用方页面中自行提前引入(gulpfile.js)。

这一点在仓库的示例页 umd.html 中有直接体现:页面先加载 React 与 ReactDOM 的 UMD 文件,再加载 antd-mobile 的 UMD 产物,然后通过 window.antdMobile.Button 等全局成员使用组件。

四、CSS 资源:style.css 与 css-vars-patch.css

预构建产物中的 CSS 共两份:

/bundle/style.css
/bundle/css-vars-patch.css

4.1 style.css:全量组件样式

style.css 汇总了所有组件的样式,覆盖按钮、弹层、表单、导航等全部内置组件。它由构建流程中的 buildStyle(gulpfile.js)从 src/**/*.less 编译而来,并经过 autoprefixer 处理(目标 iOS >= 10, Chrome >= 49)。vite 打包时各格式产物共享同名 style.css,构建脚本中的注释也专门说明了这一点("Let it step by step since style.css is same name",见 gulpfile.js)。

4.2 css-vars-patch.css:CSS 变量降级补丁

antd-mobile 的样式体系建立在 CSS 变量之上,而 iOS 9 及部分老内核不支持 CSS 变量。为此项目从 5.14.0 版本开始提供补丁文件,其源码位于 src/global/css-vars-patch.less:

@supports not (color: var(--adm-color-text)) {
  @import '../components/button/button.patch.less';
  // ... 各组件补丁样式
}

它通过 @supports 自动检测浏览器是否支持 CSS 变量,仅在不支持时才生效。构建阶段由 copyPatchStyle(gulpfile.js)将编译后的 lib/es/global/css-vars-patch.css 复制为 lib/bundle/css-vars-patch.css。

注意:补丁生效时,所有依赖 CSS 变量的能力(主题定制、暗色模式、基于变量的组件微调)将失效。它在绝大多数现代浏览器中不会产生任何影响。

4.3 2x 项目的对应产物

如果项目使用 antd-mobile 的 2x(像素翻倍)方案,构建流程会额外生成 lib/2x/ 目录(init2xFolder 与 build2xCSS,见 gulpfile.js),其中同样包含补丁文件 antd-mobile/2x/bundle/css-vars-patch.css,相关说明见 CSS 变量指南。

五、正确组合引入:JS 与 CSS 缺一不可

预构建的 JS 文件中不包含任何 CSS 内容,因此通常的用法是:先引入某一版本的 JS 产物(例如 /bundle/antd-mobile.umd.js),再额外引入 /bundle/style.css,二者缺一不可,否则组件会失去全部样式。

5.1 原生 HTML 引入示例

参考仓库中的 umd.html 示例,一个可直接运行的页面结构如下:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Hello antd-mobile</title>
    <!-- 先引入 React 与 ReactDOM 的 UMD 版本 -->
    <script src="https://unpkg.com/react@17/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@17/umd/react-dom.development.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <!-- 再引入 antd-mobile 的 UMD 产物与全量样式 -->
    <script src="./lib/bundle/antd-mobile.umd.js"></script>
    <link rel="stylesheet" href="./lib/bundle/style.css" />
    <script>
      const { Button, ErrorBlock } = window.antdMobile
      ReactDOM.render(
        <div>
          <Button color='primary'>123</Button>
          <ErrorBlock />
        </div>,
        document.getElementById('root')
      )
    </script>
  </body>
</html>

要点总结:

  1. 加载顺序:React / ReactDOM → antd-mobile UMD → style.css;
  2. 使用方式:通过全局对象 window.antdMobile 解构出 Button、ErrorBlock 等组件;
  3. 生产环境:请把示例中的 .development.js 换成压缩后的生产版 React 与 antd-mobile 产物。

5.2 与 npm 模块化引入的关系

如果你使用 npm + 打包工具(webpack 4+、rollup 等),antd-mobile 的包入口已配置好 main: "./cjs/index.js"、module: "./es/index.js"(package.json),直接 import { Button } from 'antd-mobile' 即可按 Tree Shaking 机制按需加载,无需关心 bundle 产物。预构建产物面向的是无构建工具的 CDN 场景,两者的取舍可参考按需加载指南。

六、如何获取这些预构建产物

6.1 npm 包内路径

安装 antd-mobile 后,上述文件位于包内 bundle/ 目录(本地仓库中对应构建输出目录 lib/bundle/)。package.json 还声明了 unpkg: "./umd/antd-mobile.js" 字段(package.json),供 CDN 服务自动定位 UMD 入口。

6.2 通过公共 CDN 获取

这些文件也可直接从 unpkg、jsdelivr 等公共 CDN 获取:在对应 CDN 上按 antd-mobile@5 的 bundle 目录浏览即可找到全部产物。FAQ 文档也确认了"antd-mobile 提供 CDN 上的 UMD 包"这一事实(见 docs/guide/faq.en.md)。

七、构建原理与工程细节

理解预构建产物的生成链路,有助于你在二次封装或排查体积问题时有的放矢。仓库根目录执行 npm run build(即 gulp)时的默认任务序列为(gulpfile.js):

clean → buildES → buildCJS → (buildDeclaration ∥ buildStyle) → copyAssets
      → copyMetaFiles → generatePackageJSON
      → buildBundles(vite 产出 cjs/es/umd 的开发版与生产版)
      → init2xFolder + build2xCSS(2x 版本)
      → umdWebpack(webpack + Babel 产出兼容版 UMD)
      → copyUmd(重命名为 antd-mobile.compatible.umd.js)
      → copyPatchStyle(产出 css-vars-patch.css,含 2x 版本)

几个值得注意的细节:

  • 模块格式:cjs 与 es 产物的入口是编译后的 lib/es/index.js,而 CommonJS 版本通过 buildCJS 对 es 产物做模块格式转换(gulpfile.js);
  • 体积治理:size-limit 将 antd-mobile.es.js 控制在 200 kB 以内,配合 Tree Shaking 保证按需引入时的体积表现;
  • 样式分离:JS 产物刻意不内联 CSS,因此所有预构建用法都必须手动补充 style.css,这是本项目所有 CDN 集成方案的统一前提。

结语

预构建产物是 antd-mobile 面向"零构建、纯 CDN"场景的完整交付形态:选择 .development 版本用于调试、压缩版用于生产;在需要兼容老内核时选用 Babel 处理过的 antd-mobile.compatible.umd.js;并始终记得在 JS 之外引入 style.css(低版本浏览器视情况追加 css-vars-patch.css)。结合 gulpfile.js、umd.html 与 package.json 中的源码与配置,你可以完整复现并验证文档所述的每一种组合方式。

登录后查看全文
ant-design-mobile