微信小程序分包加载优化：主包瘦身与首屏提速实战

微信小程序的主包体积上限是 2MB，很多项目在接入第三方 SDK 之后才发现无处可退。分包加载是官方给出的解法：把页面按业务切块，用户只下载当前需要的资源。下面从体积限制讲起，给出 subPackages 的完整配置写法，再落到主包瘦身的具体手段。

一、为什么要分包：主包体积的硬限制

1. 体积上限与审核规则

小程序整体包体积上限 20MB，其中主包不得超过 2MB，单个分包同样是 2MB。主包在启动时必须完整下载并执行，分包只在用户跳转到对应页面时才拉取。最常见的踩坑点是把 tabBar 页面放进分包——tabBar 页面必须位于主包，否则真机上会直接白屏。

2. 主包过大的真实代价

主包体积直接影响冷启动时间。按 4G 网络、单次 RTT 40ms 估算，主包每增加 300KB，首次下载与解析大约多耗时 100 至 200ms。更隐蔽的问题是开发者工具里看不到真实差异：只有真机预览才能反映真实下载耗时。

二、分包配置怎么写：三种分包形式

1. 普通分包配置

在 app.json 中新增 subPackages 数组，每项包含 root 与 pages 两个字段。root 是分包根目录，pages 里的路径相对 root 书写，不要再重复写一遍 root。

{
  "pages": ["pages/index/index", "pages/log/list"],
  "subPackages": [
    {
      "root": "packageOrder",
      "pages": ["list/list", "detail/detail"]
    },
    {
      "root": "packageUser",
      "pages": ["profile/profile"]
    }
  ]
}

分包内页面跳转要写绝对路径，例如 /packageOrder/list/list。主包不能引用分包内的模块，但分包可以引用主包的公共模块，所以请求封装、工具函数仍应留在主包复用。

2. 独立分包与分包预下载

独立分包用 independent 字段声明，它可以不依赖主包直接运行，适合活动页、广告落地页这类要求秒开的场景。代价是独立分包无法读取主包的全局状态与公共组件，需要自带一份精简依赖。

分包预下载在 app.json 的 preloadRule 中配置，用户到达指定页面时提前拉取目标分包，把首次跳转的等待时间前置到空闲时段。

{
  "preloadRule": {
    "pages/index/index": {
      "network": "wifi",
      "packages": ["packageOrder"]
    }
  }
}

network 可填 all 或 wifi，建议只在 wifi 下预下载，避免在移动网络下额外消耗用户流量。

三、体积优化的具体手法

1. 图片与静态资源外置

主包里占用最大的一块通常是图片。凡是超过 30KB 的图片、字体文件与图标集，都应该移到 CDN 后通过 https 地址引用。小程序不允许外链 JavaScript，但图片与媒体资源可以外链。必须内联时优先用 WebP，同等画质体积比 PNG 小 30% 到 50%。

2. 依赖与代码层面的瘦身

先用 webpack 或 vite 的体积分析插件打一份报告，逐项排查收益点。实践中收益明显的有两处：把 moment.js 换成 dayjs，体积从约 230KB 降到 7KB；按需引入组件库，避免整包引入 Vant 或 antd-mini。建议在 CI 里加一条 gzip 后体积断言，超过阈值直接构建失败，防止体积悄悄回涨。

关键配置提示

• tabBar 页面、公共组件与工具函数必须留在主包，分包无法反向引用它们。
• 分包预下载只在 wifi 下开启，移动网络预下载会明显增加用户的流量消耗。