多端工程化怎么落地:uni-app Vue3 + Vite 的条件编译与分包预算
有个项目我们维护到第三年,某次发版前要删掉一个 Android 专属的分享按钮。改的人花了四十分钟才定位到代码在哪——它不在业务目录,藏在一个 700 多行的 #ifdef 分支文件里。
这一讲要解决的就是这类问题:怎么让平台差异只出现在该出现的地方,怎么让体积预算变成一个能被流水线拦住的东西。基线与工具版本:uni-app Vue3(npm 包版本以 3.0.0- 开头接一段构建号,跟 HBuilderX 版本对齐)+ Vite,截至 2026 年 11 月。
1. 先明确这一讲要让你做到什么
学完这一讲,你应该能做到四件事:能判断一个项目该用 CLI 工程还是 HBuilderX 工程,或者两者兼用;能把散落全仓的条件编译收敛到一个目录里,并能解释为什么必须收敛;能独立算出一个小程序主包的体积预算,并在 CI 里把它拦下来;能解释为什么 manualChunks 在小程序端不起作用,转而用真正有效的三种手段。
下面这张图是本讲在你整条跨端知识线上的位置。
先记住一句话:工程化不是配置项的集合,是把「平台差异」和「体积资源」这两类稀缺物集中管理。
导入案例:一次上传被拒
某项目周四下午要发版。构建成功,上传微信后台时被拒,提示主包超过 2MB。三个人的第一反应都是"删点东西",于是有人把富文本组件注释掉,有人把图标换成在线 CDN。周五重新上传,过了。下周二又超了。
问题不在那次 PR,在于这个项目从来没有"主包该有多大"的阈值,也没有任何东西在 PR 阶段拦住它。这一个案例会贯穿全讲:后面每一节都在回答"把阈值放哪、谁来守"。
2. 目录约定:两种工程结构不是一回事
第一个容易卡住的地方是路径。HBuilderX 创建的工程,manifest.json 在项目根目录;CLI 创建的工程,manifest.json 在 src 目录下。从 HBuilderX 迁到 CLI 的项目第一次构建失败,通常就是因为文件还在根目录待着。
CLI 工程的初始化与常用脚本:
npx degit dcloudio/uni-preset-vue#vite my-app
cd my-app && npm i
# package.json 里的脚本约定
# "dev:mp-weixin": "uni -p mp-weixin"
# "build:h5": "uni build"
# "build:mp-weixin": "uni build -p mp-weixin"预期输出:degit 结束后目录里有 src/,src/manifest.json 与 src/pages.json 同时存在。如果 manifest.json 出现在根目录,构建会成功但配置不生效——这是最难发现的一类错误。
| 关注点 | CLI 工程 | HBuilderX 工程 | 取舍 |
|---|---|---|---|
| 配置文件位置 | src/manifest.json、src/pages.json | 根目录 | 迁移时必改 |
| CI/CD | 可完全脚本化 | 依赖 GUI | 多人团队选 CLI |
| uts 与原生插件调试 | 需配合 HBuilderX | 原生支持 | 重原生项目留 HBuilderX |
| 鸿蒙本地打包 | 只能借 HBuilderX | 支持 | 鸿蒙项目绕不开 |
现实里的做法一般是双轨:日常开发和 CI 走 CLI,打包(尤其鸿蒙与自定义基座)走 HBuilderX,两边共用同一份 src。代价是要维护两份忽略规则,收益是流水线能自动跑。
Vite 侧配置很薄,因为绝大部分编译逻辑由 @dcloudio/vite-plugin-uni 接管了:
// vite.config.js
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
export default defineConfig({
plugins: [uni()],
build: {
// 小程序单文件体积敏感,关掉内联,避免 base64 把包撑大
assetsInlineLimit: 0,
cssCodeSplit: true
},
define: {
// define 的值必须 JSON.stringify,否则会被当成变量名替换
__BUILD_ENV__: JSON.stringify(process.env.BUILD_ENV || 'prod')
}
})一个与 uni-app 无关的低级错误
define 里直接写字符串而不 JSON.stringify,产物里会出现 foo is not defined。这是 Vite 层面最高频的报错,跟跨端没有关系。
多环境走 Vite 标准约定:根目录放 .env、.env.test、.env.production,只有 VITE_ 前缀的变量注入客户端,代码里用 import.meta.env.VITE_API_BASE 读。不要用 process.env.NODE_ENV 兼做环境判断,它表达的是"开发还是生产构建",一个测试环境的生产构建会让所有分支同时失效。
3. 条件编译:四种载体与一条收敛纪律
条件编译的能力在四个位置一致,只是注释语法不同:
| 载体 | 语法 | 典型用途 |
|---|---|---|
| template | <!-- #ifdef MP-WEIXIN --> | 平台专属组件、广告位 |
| style | /* #ifdef H5 */ | 平台专属样式覆盖 |
| script | // #ifdef APP-PLUS | API 分支、原生能力调用 |
| 配置文件 | // #ifdef H5 | pages.json / manifest.json 里的平台配置 |
高频平台标识要背下来:MP-WEIXIN、MP-ALIPAY、MP-TOUTIAO、MP(全部小程序)、H5、APP-PLUS(全部 App)、APP-ANDROID、APP-IOS、APP-HARMONY。支持 || 与 !,例如 // #ifdef H5 || APP-PLUS。
定义:条件编译是在构建期按目标平台删除源码片段,被删掉的代码不会进入产物,也不参与该平台的语法检查。
反例:把条件编译当运行时开关用。写成
if (platform === 'h5')的代码会完整进入所有平台的产物,体积和加载时间照付。
真正决定成败的不是语法,是纪律:条件编译只允许出现在 adapter 目录里,业务代码一行都不许有。否则三年后你会拿到一个八百行的 if/else 文件,且没人敢删任何分支。
// src/adapter/share.js —— 平台差异只出现在这一层
// 业务侧统一 import { share } from '@/adapter/share'
export function share({ title, path, imageUrl }) {
// #ifdef MP-WEIXIN
return { type: 'weixin-session', title, path, imageUrl }
// #endif
// #ifdef APP-PLUS
const sweixin = plus.share.getServices().find(s => s.id === 'weixin')
if (!sweixin) return plus.nativeUI.toast('未安装微信')
return { type: 'app-plus', service: sweixin, title, path }
// #endif
// #ifdef H5
// H5 没有统一分享能力,交给调用方渲染分享面板
return { type: 'h5-fallback', title, path }
// #endif
}这里有一处必须记住的行为:条件编译在构建期删代码,所以 #ifdef APP-PLUS 里的语法错误在 H5 构建时不会报。CI 里不把目标平台全量编一遍,等于这条分支从来没被验证过。
4. 分包:预算先算,代码后写
截至 2026 年 11 月,微信小程序的口径是:所有分包合计不超过 30MB(服务商代开发 20MB),单个分包与主包各不超过 2MB。预下载另有约束:同一分包内页面共享 2MB 预下载限额,超了打包校验就失败。
这 2MB 是硬约束,不是优化建议。主包塞满的表现是构建通过、上传被拒,或者勉强过审但首屏慢到用户流失。
// src/pages.json
{
"pages": [
{ "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } },
{ "path": "pages/mine/mine", "style": { "navigationBarTitleText": "我的" } }
],
"subPackages": [
{
"root": "pkg-order",
"pages": [
{ "path": "list/list", "style": { "navigationBarTitleText": "订单" } },
{ "path": "detail/detail" }
]
},
{
"root": "pkg-market",
"pages": [{ "path": "activity/activity" }]
}
],
"preloadRule": {
"pages/index/index": { "network": "all", "packages": ["pkg-order"] },
"pkg-order/list/list": { "network": "wifi", "packages": ["pkg-market"] }
}
}四个必须知道的行为差异:subPackages 在 H5 端不支持,配了不起作用也不报错,所以别把 H5 体积优化寄托在分包上;preloadRule 只在小程序端生效(微信、QQ、抖音、支付宝、京东),且是进页面时触发,救不了"点了才下载"的场景;独立分包("independent": true)能脱离主包启动,但主包的 App.vue、全局样式、公共组件全拿不到,只适合分享落地页;分包异步化能解决两个分包共用组件,代价是首次调用要等加载,交互上必须给 loading。
小程序端还有两个开关容易漏:
// src/manifest.json
{
"mp-weixin": {
"appid": "wx************",
"lazyCodeLoading": "requiredComponents",
"optimization": { "subPackages": true }
}
}lazyCodeLoading 砍掉的是"启动时把所有组件注入一遍"的固定开销,对首屏启动的改善通常比任何代码拆分都直接。App 端想拿同样的收益,得在 app-plus.optimization.subPackages 里单独开,并配 runmode: liberate。
5. 公共依赖:为什么 manualChunks 在小程序端没用
这是 Vue3 + Vite 项目最反直觉的一点:build.rollupOptions.output.manualChunks 对小程序端几乎无效。小程序的产物结构由页面与分包目录决定,uni 编译器按页面入口产出 common/vendor.js,你手写的 chunk 策略只影响 H5 与 App。指望用 manualChunks 把 UI 库挪出主包,方向从一开始就错了。
真正有效的三种手段:easycom 自动按需(配置后组件被用到才打进对应页面依赖,不必手写 import);依赖分级(主包必需、分包可用、仅个别页面三类,后两类一律不进主包);替代重库(moment 换 dayjs、lodash 换按需引入或手写工具函数)。一个 moment 的语言包就够顶掉 200KB。
所以体积治理的第一步不是改 vite.config.js,是承认这份配置管不到小程序。
同一份源码在三个目标平台上的产物结构完全不同:小程序是"主包 + 若干分包"的目录树,H5 是 chunk 图,App 是合并后的 js 包。所以体积治理必须按平台分别设阈值,用一套指标管三端只会得到错误结论。
6. 动手任务与三处常见误解
动手任务:把下面这个脚本放进 scripts/check-size.sh,接在 build:mp-weixin 之后跑,预期输出是主包体积与上限的对比,超了返回非零退出码。
#!/usr/bin/env bash
set -euo pipefail
DIST="dist/build/mp-weixin" # CLI 工程产物;HBuilderX 工程是 unpackage/dist/build/mp-weixin
LIMIT_KB=1638 # 1.6MB,给 2MB 上限留 400KB 余量
SUBS=("pkg-order" "pkg-market") # 与 pages.json 的 subPackages.root 保持一致
total=$(du -sk "$DIST" | cut -f1)
sub=0
for d in "${SUBS[@]}"; do
[ -d "$DIST/$d" ] && sub=$((sub + $(du -sk "$DIST/$d" | cut -f1)))
done
main_kb=$((total - sub))
echo "主包: ${main_kb}KB / 上限 ${LIMIT_KB}KB;整包: ${total}KB"
if [ "$main_kb" -gt "$LIMIT_KB" ]; then
echo "主包超预算,按目录看占用:"
du -sk "$DIST"/* | sort -rn | head -10
exit 1
fi
echo "主包体积通过"预期输出形如 主包: 1420KB / 上限 1638KB;整包: 5980KB,末行打印"主包体积通过"。这个脚本很粗糙,但它拦的是"某次 PR 顺手 import 了一个 300KB 的库",而这恰恰是主包膨胀的绝大多数原因。
观察量怎么取,三端三套量法:
| 目标 | 工具 | 关键指标 | 建议阈值 |
|---|---|---|---|
| 微信小程序 | 开发者工具「代码依赖分析」 | 主包体积、单分包体积 | 主包 < 1.6MB |
| H5 | rollup-plugin-visualizer | 首屏 chunk、重复依赖 | 首屏 JS gzip < 200KB |
| App | HBuilderX 打包日志 + unpackage/dist | app-service.js 体积 | 关注冷启动耗时而非体积 |
三处常见误解:
很多人以为分包只是"把文件挪到别的目录",实际上分包切分决定的是下载顺序与预下载边界,切错会让用户多点一次等待。
很多人以为 optimization.subPackages 配一次就两端生效,实际上小程序端读 mp-weixin.optimization,App 端读 app-plus.optimization,两处互不相干。顺带一提,字段名是 subPackages,写成全小写 subpackages 会被静默忽略。
很多人以为 H5 也能用小程序的预下载,实际上 preloadRule 与 subPackages 在 H5 端都不生效,H5 的体积问题要靠 code split 与路由懒加载单独解决。
留两道题给课堂:如果主包超预算 300KB,而你只能动一个文件,你会先查哪个?独立分包里为什么绝对不能放登录态依赖?这两道题的答案都不在文档里,得靠动手跑一次才清楚。
最后一张表,五个中英对照,考试会用到:
| 中文 | 英文 | 一句话定义 |
|---|---|---|
| 条件编译 | conditional compilation | 构建期按平台删代码的机制,删掉的片段不进产物 |
| 分包 | subpackage | 主包之外按需下载的代码包 |
| 预下载 | preload rule | 进页面时提前拉取指定分包 |
| 按需注入 | lazy code loading | 启动时只注入实际用到的自定义组件 |
| easycom | — | 按目录约定自动注册组件的机制 |
这一讲没有讲怎么做多端差异的抽象层。那件事的难点不在技术,在「谁来拍板哪些差异允许存在」,属于团队协作问题,放到另一讲。
截至 2026 年 11 月,分包体积与预下载的准确口径以微信官方分包加载文档为准。这个数字微信改过几轮,别信任何博客里的旧值。