
微信小程序分包实战总结
微信小程序分包实战总结,包括分包的基本概念、分包的实现步骤、分包的注意事项等
本文原发表于「Eric 技术圈」,现迁移并修订至夏有木工作室官网。
在微信小程序开发过程中,相信很多开发者都遇到过这样的困扰:辛苦开发完成的小程序,在准备上传发布时却被提示主包或分包大小超过了 2M 的限制。这成了企业级应用功能扩展的一道门槛,可以通过合理的分包策略,不仅能解决这个问题,还能显著提升小程序的启动速度和用户体验。
分包之后的打开效果,欢迎大家免费试用体验👇

为什么需要分包?
小程序分包技术的核心思想很简单:将一个完整的小程序项目合理拆分为主包和多个子包,既能突破单包大小限制,又能提升加载性能。
具体来说,小程序启动时只需要下载核心的主包和 Tab 页面,当用户真正需要访问某个功能模块时,再动态加载对应的分包。这种按需加载的方式,就像我们平时使用的流媒体服务一样,用到什么加载什么,大大提升了用户体验。
值得一提的是,微信还提供了"独立分包"功能,这类分包完全独立于主包运行,启动速度更快,特别适合那些功能相对独立的场景,比如活动页面、工具类功能等。
在开始分包之前,我们先了解一下官方的限制规则:
- 整个小程序所有分包总大小不超过 30M(服务商代开发的小程序限制为 20M)
- 单个分包或主包大小不能超过 2M
主包"发胖"的常见原因
在实际开发中,主包容易超限主要有以下几个原因:
-
UI 组件库的引入:引入了某个 UI 组件库,哪怕只用了其中几个组件,整个库的几百 KB 也会在代码依赖分析中被计算在内。
-
静态资源管理不当:把大量图片、字体文件直接放在项目里,这些资源会直接增加包体积。特别是一些高清图片,很容易就超过微信 200KB 的单文件限制。
-
npm 包的"连坐效应":通过 npm 安装的第三方包,不管放在哪个分包里,最终都会被打包到主包中,这是很多开发者容易忽略的坑。
-
业务代码自然增长:随着功能迭代,页面和组件代码越来越多,这是正常的业务发展,但也是包体积增长的主要原因。
分包前的"瘦身"策略
在考虑分包之前,我们可以先尝试给主包"减减肥":
-
精简 UI 组件引入:仔细检查 app.json 中的组件配置,移除那些实际没有使用的组件。按需引入,而不是一股脑全部导入。
-
静态资源上云:将图片、音频等静态资源迁移到 CDN,这样既能减少包体积,又能提升资源加载速度。如果必须本地存储,记得先压缩处理。
-
提取公共逻辑:把多个页面共用的业务逻辑抽取成自定义组件或 Behaviors,避免重复代码,一举两得。
-
第三方包精简:审视项目中的 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 组件、业务代码、自定义组件和一些静态资源。

面对这种情况,我采用了组合拳的方式来解决:
- 静态资源迁移:将图片等静态资源迁移到 CDN
- 功能模块分包:按业务功能将代码拆分到不同分包
- 组件下沉:将非通用的自定义组件和 JS 逻辑移到对应的分包中
分包结构设计
在 app.json 中,我按照业务模块划分了几个分包,比如采购模块(pkg_purchase)、库存模块(pkg_inventory)等。然后将原本在 pages 目录下的页面代码,按功能归属移动到对应的分包目录中。

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

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

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

分包的一些限制和思考
虽然分包技术一定程度上解决包体积问题,但在实际使用中,我们还是会遇到一些限制,需要提前了解:
体积限制依然存在 2MB 的单包限制对于复杂项目来说确实比较紧张,特别是当分包本身也接近这个限制时,可能需要进行二次拆分,这会增加项目的复杂度。
npm 依赖的"主包集中"问题 这是一个比较容易被忽视的点:无论第三方 UI 组件在哪个分包中使用,通过 npm 安装的依赖最终都会被打包到主包中。比如我的项目中,主包 1.18MB 里有 856KB 都是 UI 组件库,这部分是无法通过分包来优化的。
插件的主包限制 微信小程序的插件(如直播插件)只能在主包中使用,无法分包。一个直播插件就可能占用 1MB 的空间,这对主包来说是不小的压力。
公共代码的归属问题 公共组件和工具方法只能放在主包中,这样所有分包都能访问。但如果多个分包共用的逻辑在主包中没有引用的话,会收到代码质量优化的提示。
一些应对建议
面对这些限制,我们可以:
- 在项目初期就提前考虑分包策略,避免后期重构的复杂性,至少代码的耦合度不要太高,不便于后期的分包处理
- 谨慎选择第三方依赖,优先考虑体积较小的库
- 对于公共逻辑,在保证代码复用的前提下,适当考虑在分包中实现特定版本
- 定期审查和清理不必要的依赖和代码
总的来说,分包是解决小程序体积问题的有效方案,虽然有一些限制,但合理规划后能够很好地支撑项目的长期发展。



