antd-mobile 预构建产物(Pre-Built Bundles)完整指南:JS/CSS 资源选型、兼容性与引入方式

原创2026-09-22 09:58:121,938 阅读
文章标签:UI组件前端移动开发

antd-mobile 预构建产物(Pre-Built Bundles)完整指南:JS/CSS 资源选型、兼容性与引入方式

预构建产物(Pre-Built Bundles)是 antd-mobile 在发布 npm 包时随包附带的一整套"开箱即用"资源,包括多个格式、多个构建模式的 JS 文件与配套 CSS 文件。本指南将以 docs/guide/pre-built-bundles.zh.md 为主线,结合仓库中的 gulpfile.js、umd.html、package.json 等源码证据,系统讲解每类产物的用途、兼容性边界、正确的引入姿势,以及它们背后真实的构建链路,帮助你在 CDN 直引、HTML 页面或非打包工具场景下正确选用 antd-mobile 资源。

一、预构建产物概览:JS 与 CSS 两大资源族

antd-mobile 提供的预构建产物分为两部分:JS 资源与 CSS 资源。它们共同存放在 npm 包内的 bundle 目录中,最终随包发布后可通过 CDN 或本地路径访问。

  • JS 资源:涵盖 cjs、es、umd 三种模块格式,每种格式又区分 development(未压缩、仅供开发调试)与 production(压缩优化、面向生产)两个版本。
  • CSS 资源:提供 style.css(完整样式)与 css-vars-patch.css(CSS 变量降级补丁)两个文件。

理解这组产物的关键前提是:这些预构建的 JS 文件中不包含任何 CSS 内容。也就是说,无论你选择哪个 JS 文件,都需要额外引入对应的 CSS 文件,页面才能正确渲染组件样式。

二、JS 资源详解:三种模块格式与开发/生产双版本

2.1 开发环境产物(仅限开发调试)

以下三个文件带有 .development 标识,仅适用于开发环境,不适合用于生产环境:

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

从构建源码可以印证这一点:gulpfile.js 中 getViteConfigForPackage 会根据 env 参数决定是否压缩——minify: isProd ? 'esbuild' : false,并且产物文件名按 ${name}.${format}${isProd ? '' : .${env}}.js 规则生成,因此开发版本的文件名会带上 .development 后缀,且未经过压缩混淆,便于调试时查看源码堆栈。构建时还会通过 define 注入 process.env.NODE_ENV 为对应值,开发版本注入的是 "development"。

2.2 生产环境产物(压缩优化后)

压缩优化后可用于生产环境的产物如下:

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

其中 cjs、es 两个文件供 Node 环境或现代打包工具(如 Webpack、Rollup、Vite)通过模块解析使用,umd 系列则用于浏览器 <script> 直引。buildBundles(gulpfile.js)会依次以 development 与 production 两种模式、['es', 'cjs', 'umd'] 三种 format 调用 Vite 构建,产物统一输出到 ./lib/bundle 目录;同时把 react、react-dom 声明为 external,因此产物中不包含 React 运行时,需要页面自行引入 React。

2.3 两种 UMD 版本:普通版与 Babel 兼容版

UMD 文件提供了两个版本,这是预构建产物中最需要理解清楚的一处差异:

文件 是否经过 Babel 处理 兼容性
/bundle/antd-mobile.umd.js 否(未处理) Chrome >= 61、iOS >= 11
/bundle/antd-mobile.compatible.umd.js 是(已处理) Chrome >= 49、iOS >= 9
  • antd-mobile.umd.js:由 Vite 直接构建产出,未经过 Babel 转译,依赖浏览器对现代 ES 语法与 Web API 的原生支持,适合较新环境,体积与执行性能更优。这一点在构建配置中也有体现:getViteConfigForPackage 设置了 cssTarget: 'chrome61',即以 Chrome 61 为最低目标基线。
  • antd-mobile.compatible.umd.js:由 Webpack 配合 @babel/preset-env 二次构建,把语法转译为旧浏览器可执行的 ES5 级别代码。仓库中的 umdWebpack(gulpfile.js)使用 Babel 的 targets: { chrome: '49', ios: '9' } 配置,产物先输出为 lib/umd/antd-mobile.js,再由 copyUmd(gulpfile.js)重命名为 antd-mobile.compatible.umd.js 放入 bundle 目录。如果你需要兼容老机型(例如 iOS 9~10 的旧款 iPhone 或老版本 Android WebView),请选择这个版本。

顺带一提,package.json 中的 GravityCDN 字段与 unpkg 字段均指向 ./umd/antd-mobile.js,也就是上面提到的 Webpack 兼容版产物,这说明 CDN 场景默认投放的即是兼容版本。

三、CSS 资源详解:style.css 与 css-vars-patch.css

CSS 资源共两个文件:

/bundle/css-vars-patch.css
/bundle/style.css
  • style.css:完整的组件样式文件,包含了 antd-mobile 所有组件的样式。它由 gulpfile.js 中的 buildStyle(gulpfile.js)将 src 目录下所有组件的 .less 源码编译而来(排除 demos、tests 与 *.patch.less),并经过 Autoprefixer 处理。其底层样式依赖 CSS 变量体系(如 --adm-color-text、--adm-color-primary),这些变量定义在 src/global/theme-default.less 与 src/global/theme-dark.less 中,并在 src/global/global.less 里被统一引入。
  • css-vars-patch.css:CSS 变量的降级补丁。当浏览器不支持 CSS 变量(var())时,antd-mobile 无法正常渲染主题色等样式,此时需要这个补丁来提供兜底。它的源码是 src/global/css-vars-patch.less,内容以 @supports not (color: var(--adm-color-text)) 包裹,在该条件下引入各组件(Button、Cascader、Popup、Modal、Tabs、Toast 等十余个组件)的 *.patch.less 修复样式。构建时由 copyPatchStyle(gulpfile.js)把编译后的文件复制到 bundle 目录。

关于是否需要 css-vars-patch.css:现代浏览器(Chrome 49+、iOS 9.3+ 均已支持 CSS 变量)默认场景下引入 style.css 即可;只有当你的目标环境确实不支持 CSS 变量时,才需要额外追加 css-vars-patch.css。

四、如何正确引入:CDN 直引与本地引用的完整示例

由于 JS 产物不包含样式,标准的引入方式是:选择一个 JS 文件 + 引入 style.css。

4.1 通过 CDN 或本地路径直接引用

以生产环境、需要兼容老浏览器的场景为例:

<!-- 1. 先引入 React 运行时(UMD 产物不内置 React) -->
<script src="https://你的静态资源域名/react@18/umd/react.production.min.js"></script>
<script src="https://你的静态资源域名/react-dom@18/umd/react-dom.production.min.js"></script>

<!-- 2. 引入 antd-mobile 的 UMD 产物(兼容版) -->
<script src="https://你的静态资源域名/antd-mobile/bundle/antd-mobile.compatible.umd.js"></script>

<!-- 3. 引入配套样式 -->
<link rel="stylesheet" href="https://你的静态资源域名/antd-mobile/bundle/style.css" />

引入后,所有组件会挂载到全局命名空间 window.antdMobile 上,可直接解构使用:

<script>
  const { Button, ErrorBlock } = window.antdMobile
  ReactDOM.render(
    <div>
      <Button color='primary'>确认</Button>
      <ErrorBlock />
    </div>,
    document.getElementById('root')
  )
</script>

上面这个用法正是仓库中 umd.html 的真实演示写法:它依次引入 React、ReactDOM、./lib/bundle/antd-mobile.umd.js 与 ./lib/bundle/style.css,然后通过 window.antdMobile 取出 Button、ErrorBlock 两个组件完成渲染。如果你在本地 clone 了本仓库,可以直接参考这个 HTML 文件来验证 UMD 产物的引入方式。

4.2 在打包工具 / Node 环境中使用 cjs 与 es 产物

  • ES Module 场景:/bundle/antd-mobile.es.js 面向现代打包器,配合 package.json 中的 module 与 types 字段(分别指向 ./es/index.js 与 ./es/index.d.ts)可获得类型提示与按需构建优化。
  • CommonJS 场景:/bundle/antd-mobile.cjs.js 面向 Node 环境与需要 CJS 解析的打包配置,package.json 中的 main 字段即指向 ./cjs/index.js。

另外,package.json 中声明了 sideEffects,其中包含 **/*.css、**/*.less、./es/global/index.js 等条目。这意味着当你使用 Tree Shaking 打包时,这些带副作用的样式与全局初始化文件不会被错误地摇掉,从而保证 src/global/index.ts(注册全局样式与移动端 touchstart 事件处理)能正常生效。

五、从源码看预构建产物的完整构建链路

如果你对产物本身是怎么来的感兴趣,可以在 gulpfile.js 的默认任务序列中找到答案。整条流水线大致如下:

  1. clean:清空旧的 lib 输出目录;
  2. buildES + buildCJS:将 src/index.ts 及全部组件源码编译为 ES Module 与 CommonJS 两套模块代码,其中 babel-transform-less-to-css.js 会把源码中 import ... from 'xxx.less' 的导入自动改写为 .css,让产物只依赖 CSS 文件而非 Less 源文件;
  3. buildStyle:把所有组件 Less 编译为 CSS,并经过 Autoprefixer(目标 iOS >= 10, Chrome >= 49)处理;
  4. buildBundles:以 Vite 分别产出 es / cjs / umd 的 development 与 production 版本到 lib/bundle;
  5. umdWebpack + copyUmd:用 Webpack + Babel(目标 chrome: 49, ios: 9)产出兼容版 UMD 并放入 bundle;
  6. copyPatchStyle:把 css-vars-patch.css 复制进 bundle。

可以看到,"两个 UMD 版本"、"CSS 与 JS 分离"、"css-vars-patch 补丁"这些产物特性,全部都能在构建脚本中找到对应的实现依据,而非文档中的主观描述。

六、选型建议与注意事项

综合上述内容,实际项目中的选型可以遵循以下原则:

  1. 永远不要在生产环境使用 .development 后缀的文件,它们未压缩且带有开发模式行为,会显著拖慢首屏加载并可能暴露调试信息。
  2. 能走打包工具就用打包工具:绝大多数 Web 项目应当通过 npm install antd-mobile 后按需引入组件,预构建 UMD 产物是为"无法使用构建工具"的场景(CDN 直引、服务端直出的静态页、低代码平台等)准备的兜底方案。
  3. 按目标浏览器选择 UMD 版本:仅需支持 Chrome >= 61、iOS >= 11 时用 antd-mobile.umd.js;需要覆盖 Chrome >= 49、iOS >= 9 的老环境时用 antd-mobile.compatible.umd.js。
  4. JS 与 CSS 必须配套引入:预构建 JS 不含任何样式,漏引 style.css 会导致组件出现但无样式;对不支持 CSS 变量的极老环境,再追加 css-vars-patch.css。
  5. React 运行时需要自行提供:UMD 产物将 React / ReactDOM 声明为 external,页面中必须先用 <script> 引入 React 才能正常渲染。

如果你希望深入探索产物背后的实现,建议按以下路径阅读仓库源码:先看 docs/guide/pre-built-bundles.zh.md 了解产物清单,再对照 gulpfile.js 理解构建过程,最后用 umd.html 做一次实际引入验证,并浏览 src/global/global.less 与 src/global/css-vars-patch.less 理解样式与补丁的真实构成。

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