微信小程序分包实战总结

本文原发表于「Eric 技术圈」，现迁移并修订至夏有木工作室官网。

在微信小程序开发过程中，相信很多开发者都遇到过这样的困扰：辛苦开发完成的小程序，在准备上传发布时却被提示主包或分包大小超过了 2M 的限制。这成了企业级应用功能扩展的一道门槛，可以通过合理的分包策略，不仅能解决这个问题，还能显著提升小程序的启动速度和用户体验。

分包之后的打开效果，欢迎大家免费试用体验👇

为什么需要分包？

小程序分包技术的核心思想很简单：将一个完整的小程序项目合理拆分为主包和多个子包，既能突破单包大小限制，又能提升加载性能。

具体来说，小程序启动时只需要下载核心的主包和 Tab 页面，当用户真正需要访问某个功能模块时，再动态加载对应的分包。这种按需加载的方式，就像我们平时使用的流媒体服务一样，用到什么加载什么，大大提升了用户体验。

值得一提的是，微信还提供了"独立分包"功能，这类分包完全独立于主包运行，启动速度更快，特别适合那些功能相对独立的场景，比如活动页面、工具类功能等。

在开始分包之前，我们先了解一下官方的限制规则：

• 整个小程序所有分包总大小不超过 30M（服务商代开发的小程序限制为 20M）
• 单个分包或主包大小不能超过 2M

主包"发胖"的常见原因

在实际开发中，主包容易超限主要有以下几个原因：

1. UI 组件库的引入：引入了某个 UI 组件库，哪怕只用了其中几个组件，整个库的几百 KB 也会在代码依赖分析中被计算在内。

2. 静态资源管理不当：把大量图片、字体文件直接放在项目里，这些资源会直接增加包体积。特别是一些高清图片，很容易就超过微信 200KB 的单文件限制。

3. npm 包的"连坐效应"：通过 npm 安装的第三方包，不管放在哪个分包里，最终都会被打包到主包中，这是很多开发者容易忽略的坑。

4. 业务代码自然增长：随着功能迭代，页面和组件代码越来越多，这是正常的业务发展，但也是包体积增长的主要原因。

分包前的"瘦身"策略

在考虑分包之前，我们可以先尝试给主包"减减肥"：

1. 精简 UI 组件引入：仔细检查 app.json 中的组件配置，移除那些实际没有使用的组件。按需引入，而不是一股脑全部导入。

2. 静态资源上云：将图片、音频等静态资源迁移到 CDN，这样既能减少包体积，又能提升资源加载速度。如果必须本地存储，记得先压缩处理。

3. 提取公共逻辑：把多个页面共用的业务逻辑抽取成自定义组件或 Behaviors，避免重复代码，一举两得。

4. 第三方包精简：审视项目中的 npm 依赖，对于只用到部分功能的大型库，考虑自己实现相关工具函数来替代。

经过这些优化后，如果主包大小仍然超过 2M（或者接近 1.5M 的警告线），那就该考虑分包方案了。分包不仅能解决体积问题，还能让小程序加载更快，用户体验更好。

分包

分包策略

分包配置说明

分包的配置其实很简单，只需要在 app.json 中添加 subPackages 字段来声明分包结构：

{
  "pages":[
    "pages/index",
    "pages/logs"
  ],
  "subPackages": [
    {
      "root": "packageA",
      "pages": [
        "pages/cat",
        "pages/dog"
      ],
      "entry": "index.js"
    }, {
      "root": "packageB",
      "name": "pack2",
      "pages": [
        "pages/apple",
        "pages/banana"
      ]
    }
  ]
}

每个分包的配置项说明如下：

分包的基本规则

理解这些规则很重要，它们决定了我们如何组织代码结构：

• 打包范围：只有在 subPackages 中声明的目录才会被分包，其他目录都会进入主包
• 主包页面：主包可以有自己的页面，就是 app.json 最外层的 pages 字段
• 目录层级：分包的根目录不能嵌套，比如 packageA 不能放在 packageB 里面
• Tab 页限制：底部导航栏（tabBar）的页面必须放在主包中

分包间的引用限制

这是很多开发者容易踩坑的地方，需要特别注意：

• JS 文件引用：分包 A 不能直接引用分包 B 的 JS 文件，但可以引用主包和自己包内的文件。不过使用 分包异步化 可以突破这个限制
• 模板引用：同样，分包 A 不能使用分包 B 的模板文件
• 静态资源：分包 A 不能使用分包 B 的图片等静态资源

简单来说，分包之间是相互隔离的，只能向上依赖主包，不能横向依赖其他分包。

实战分包过程

让我们来看看一个真实的分包案例。分包前，我的小程序主包已经达到了 2.32 MB，主要包含第三方 UI 组件、业务代码、自定义组件和一些静态资源。

面对这种情况，我采用了组合拳的方式来解决：

1. 静态资源迁移：将图片等静态资源迁移到 CDN
2. 功能模块分包：按业务功能将代码拆分到不同分包
3. 组件下沉：将非通用的自定义组件和 JS 逻辑移到对应的分包中

分包结构设计

在 app.json 中，我按照业务模块划分了几个分包，比如采购模块（pkg_purchase）、库存模块（pkg_inventory）等。然后将原本在 pages 目录下的页面代码，按功能归属移动到对应的分包目录中。

性能优化配置

为了进一步提升用户体验，我还配置了 preloadRule 属性来预加载分包。这样当用户可能需要访问某个分包时，系统会提前在后台下载，减少用户等待时间。

分包效果

经过分包处理后，主包大小成功降到了 1.18 MB，为后续功能扩展留出了充足空间。更重要的是，现在新增的业务功能都可以放到对应的分包中，主包基本不会再有大的变化。

开发者工具的检测也顺利通过，不再有体积超限的警告：

分包的一些限制和思考

虽然分包技术一定程度上解决包体积问题，但在实际使用中，我们还是会遇到一些限制，需要提前了解：

体积限制依然存在 2MB 的单包限制对于复杂项目来说确实比较紧张，特别是当分包本身也接近这个限制时，可能需要进行二次拆分，这会增加项目的复杂度。

npm 依赖的"主包集中"问题 这是一个比较容易被忽视的点：无论第三方 UI 组件在哪个分包中使用，通过 npm 安装的依赖最终都会被打包到主包中。比如我的项目中，主包 1.18MB 里有 856KB 都是 UI 组件库，这部分是无法通过分包来优化的。

插件的主包限制 微信小程序的插件（如直播插件）只能在主包中使用，无法分包。一个直播插件就可能占用 1MB 的空间，这对主包来说是不小的压力。

公共代码的归属问题 公共组件和工具方法只能放在主包中，这样所有分包都能访问。但如果多个分包共用的逻辑在主包中没有引用的话，会收到代码质量优化的提示。

一些应对建议

面对这些限制，我们可以：

• 在项目初期就提前考虑分包策略，避免后期重构的复杂性，至少代码的耦合度不要太高，不便于后期的分包处理
• 谨慎选择第三方依赖，优先考虑体积较小的库
• 对于公共逻辑，在保证代码复用的前提下，适当考虑在分包中实现特定版本
• 定期审查和清理不必要的依赖和代码

总的来说，分包是解决小程序体积问题的有效方案，虽然有一些限制，但合理规划后能够很好地支撑项目的长期发展。