antd-mobile 预构建产物(Pre-Built Bundles)完整指南:JS/CSS 资源选型、兼容性与引入方式
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 的默认任务序列中找到答案。整条流水线大致如下:
clean:清空旧的lib输出目录;buildES+buildCJS:将 src/index.ts 及全部组件源码编译为 ES Module 与 CommonJS 两套模块代码,其中 babel-transform-less-to-css.js 会把源码中import ... from 'xxx.less'的导入自动改写为.css,让产物只依赖 CSS 文件而非 Less 源文件;buildStyle:把所有组件 Less 编译为 CSS,并经过 Autoprefixer(目标iOS >= 10, Chrome >= 49)处理;buildBundles:以 Vite 分别产出 es / cjs / umd 的 development 与 production 版本到lib/bundle;umdWebpack+copyUmd:用 Webpack + Babel(目标chrome: 49, ios: 9)产出兼容版 UMD 并放入bundle;copyPatchStyle:把css-vars-patch.css复制进bundle。
可以看到,"两个 UMD 版本"、"CSS 与 JS 分离"、"css-vars-patch 补丁"这些产物特性,全部都能在构建脚本中找到对应的实现依据,而非文档中的主观描述。
六、选型建议与注意事项
综合上述内容,实际项目中的选型可以遵循以下原则:
- 永远不要在生产环境使用
.development后缀的文件,它们未压缩且带有开发模式行为,会显著拖慢首屏加载并可能暴露调试信息。 - 能走打包工具就用打包工具:绝大多数 Web 项目应当通过
npm install antd-mobile后按需引入组件,预构建 UMD 产物是为"无法使用构建工具"的场景(CDN 直引、服务端直出的静态页、低代码平台等)准备的兜底方案。 - 按目标浏览器选择 UMD 版本:仅需支持
Chrome >= 61、iOS >= 11时用antd-mobile.umd.js;需要覆盖Chrome >= 49、iOS >= 9的老环境时用antd-mobile.compatible.umd.js。 - JS 与 CSS 必须配套引入:预构建 JS 不含任何样式,漏引
style.css会导致组件出现但无样式;对不支持 CSS 变量的极老环境,再追加css-vars-patch.css。 - 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 理解样式与补丁的真实构成。