某些情况下,开发者需要将小程序划分成不同的子包,在构建时打包成不同的分包,用户在使用时按需进行加载。对小程序进行分包,可以优化小程序首次启动的下载时间,以及在多团队共同开发时可以更好的解耦协作。
在小程序启动时,默认会下载主包并启动主包内页面,当用户进入分包内某个页面时,客户端会把对应分包下载下来,下载完成后再进行展示。
目前小程序分包大小有以下限制:整个小程序所有分包大小不超过 20M,单个分包/主包大小不能超过 2M。
每个使用分包的小程序必定需要包含有一个主包。所谓的主包,即放置默认启动页面/TabBar 页面以及一些所有分包都需用到公共资源/ JS 脚本;而分包则是根据开发者的配置进行划分。
使用分包:
开发者通过在 app.json
中的 subpackages 字段声明项目的分包结构。
tabBar 页面必须在主包内。
不需要担心低版本的兼容问题。会由微信后台编译来处理旧版本客户端的兼容,后台会编译两份代码包,一份是分包后代码,另外一份是整包的兼容代码。 新客户端用分包,老客户端还是用的整包,完整包会把各个 subpackage 里面的路径放到 pages 中。
假设支持分包的小程序的目录结构如下:
那么要在 app.json 中进行如下配置:
{
// 主包
"pages":[
"pages/index",
"pages/logs"
],
// 分包
"subpackages": [
{
// 分包的根目录
"root": "packageA",
// 分包别名,分包预下载时可以使用
"name": "pack1",
// 分包页面路径,相对于分包根目录
"pages": [
"pages/cat",
"pages/dog"
],
// 分包是否是独立分包
"independent": false
},
{
"root": "packageB",
"name": "pack2",
"pages": [
"pages/apple",
"pages/banana"
],
"independent": false
}
]
}
独立分包:
独立分包可以独立于主包和其他分包运行。从独立分包中页面进入小程序时,不需要下载主包。当用户进入普通分包或主包内页面时,主包才会被下载。
开发者通过 app.json
的 subpackages 字段中的 independent 字段声明独立分包。
独立分包属于分包的一种,普通分包的所有限制都对独立分包有效。
当用户从独立分包页面启动小程序时,主包不存在,App 也不存在,此时调用getApp()
获取到的是 undefined。 当用户进入普通分包或主包内页面时,主包才会被下载,App 才会被注册,此时调用getApp()
可以获取到真正的 App。
当从独立分包启动小程序时,主包中 App 的 onLaunch 和首次 onShow 会在从独立分包页面首次进入主包或其他普通分包页面时调用。
假设小程序目录结构如下:
那么在 app.json 中要进行如下配置:
{
"pages": [
"pages/index",
"pages/logs"
],
"subpackages": [
{
"root": "moduleA",
"pages": [
"pages/rabbit",
"pages/squirrel"
]
},
{
"root": "moduleB",
"pages": [
"pages/pear",
"pages/pineapple"
],
"independent": true
}
]
}
分包预下载:
开发者可以通过配置,在进入小程序某个页面时,由框架自动预下载可能需要的分包,提升进入后续分包页面时的启动速度。对于独立分包,也可以预下载主包。
预下载分包行为在进入某个页面时触发,通过 app.json
中的 preloadRule 配置来控制。
同一个分包中的页面享有共同的预下载大小限额 2M,限额会在工具中打包时校验。
{
"pages": ["pages/index"],
"subpackages": [
{
"root": "important",
"pages": ["index"],
},
{
"root": "sub1",
"pages": ["index"],
},
{
"root": "sub2",
"pages": ["index"]
},
{
"root": "sub3",
"pages": ["index"]
},
],
"preloadRule": {
// key 是页面路径,value 是进入此页面的预下载配置
"pages/index": {
// 进入页面后预下载分包的 root 或 name。__APP__ 表示主包
"packages": ["important"],
// 在指定网络下预下载
"network": "all"
},
"sub1/index": {
"packages": ["sub2", "sub3"]
},
}
}
分包异步化:
默认情况下,除了非独立分包可以依赖主包外,分包之间不能互相使用自定义组件和 JS 代码。分包异步化使得部分跨分包的内容可以在等待下载后异步使用,从而在一定程度上解决这个限制。
跨分包自定义组件引用:
一个分包使用其他分包的自定义组件时,可能由于其他分包还未下载或注入,导致其组件处于不可用的状态。
可以通过为其他分包的自定义组件设置占位组件,先渲染占位组件作为替代,在分包下载完成后再进行替换。
// subPackageA/pages/index.json
{
"usingComponents": {
"button": "../../commonPackage/components/button",
"list": "../../subPackageB/components/full-list",
"simple-list": "../components/simple-list",
},
"componentPlaceholder": {
// 要是 button 组件不可用,就先渲染 view 组件,等待 button 组件可用后再进行替换
"button": "view",
"list": "simple-list",
}
}
跨分包 JS 代码引用:
一个分包中的代码引用其它分包的代码时,为了不让下载阻塞代码运行,需要异步获取引用的结果。
// subPackageA/index.js
// 使用回调函数风格的调用
require('../subPackageB/utils.js', utils => {
console.log(utils.whoami) // Wechat MiniProgram
}, ({mod, errMsg}) => {
console.error(`path: ${mod}, ${errMsg}`)
})
// 或者使用 Promise 风格的调用
require.async('../commonPackage/index.js').then(pkg => {
pkg.getPackageName() // 'common'
}).catch(({mod, errMsg}) => {
console.error(`path: ${mod}, ${errMsg}`)
})