Skip to content

多端工程化怎么落地: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 工程的初始化与常用脚本:

bash
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 接管了:

js
// 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-PLUSAPI 分支、原生能力调用
配置文件// #ifdef H5pages.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 文件,且没人敢删任何分支。

js
// 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 是硬约束,不是优化建议。主包塞满的表现是构建通过、上传被拒,或者勉强过审但首屏慢到用户流失。

jsonc
// 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。

小程序端还有两个开关容易漏:

jsonc
// 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 之后跑,预期输出是主包体积与上限的对比,超了返回非零退出码。

bash
#!/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
H5rollup-plugin-visualizer首屏 chunk、重复依赖首屏 JS gzip < 200KB
AppHBuilderX 打包日志 + unpackage/distapp-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 月,分包体积与预下载的准确口径以微信官方分包加载文档为准。这个数字微信改过几轮,别信任何博客里的旧值。