微信小程序分包加载功能

随着微信小程序和微信小游戏的玩法越来越丰富，微信小程序开发者对于扩大包大小的需求越来越强烈，所以微信官方团队推出了小游戏分包加载这个功能。所谓的微信小程序分包加载，即把游戏内容按一定规则拆分这几包，在首次启动时先下载必要的包，这个必要的包称之为「主包」，微信小程序开发者可以在主包内触发其它分包的下载，从而把首次启动的下载耗时分散到游戏运行中。目前微信小程序分包加载大小的限制为： 整个小游戏所有分包大小不超过 8M和单个分包/主包大小不能超过 4M。

微信小程序分包加载功能

微信小程序分包加载的使用方法

1. 分包配置

需要先在 game.json 配置分包信息。

假设游戏的目录结构如下：

├── game.js
├── game.json
├── images
│   ├── a.png
│   ├── b.png
├── stage1
│   └── game.js
│   └── images
│       ├── 1.png
│       ├── 2.png
└── stage2.js

game.json 中的配置：

{
  ...
  subpackages: [
    {
      name: 'stage1',
      root: 'stage1/' // 可以指定一个目录，目录根目录下的 game.js 会作为入口文件，目录下所有资源将会统一打包
    }, {
      name: 'stage2',
      root: 'stage2.js' // 也可以指定一个 JS 文件
    }
  ]
  ...
}

配置在 subpackages 字段内的目录或 js 文件，将按照配置打包成一个个「分包」，没有配置在 subpackages 中的目录和 js，将会被打包到主包中。

2. 分包加载

我们提供了 wx.loadSubpackage() API 来触发分包的下载，调用 wx.loadSubpackage 后，将触发分包的下载与加载，在加载完成后，通过 wx.loadSubpackage 的 success 回调来通知加载完成。

同时，wx.loadSubpackage 会返回一个 LoadSubpackageTask，可以通过 LoadSubpackageTask 获取当前下载进度。

示例代码：

const loadTask = wx.loadSubpackage({
  name: 'stage1', // name 可以填 name 或者 root success: function(res) { // 分包加载成功后通过 success 回调 },
  fail: function(res) { // 分包加载失败通过 fail 回调 }
})

loadTask.onProgressUpdate(res => { console.log('下载进度', res.progress) console.log('已经下载的数据长度', res.totalBytesWritten) console.log('预期需要下载的数据总长度', res.totalBytesExpectedToWrite)
})

老版本兼容

由微信后台编译来处理旧版本客户端的兼容，后台会编译两份代码包，一份是分包后代码，另外一份是整包的兼容代码。对于老客户端，会去下载整包代码启动。

开发者在基础库 2.1.0 以下的版本不需要调用 wx.loadSubpackage 触发加载，2.1.0 以下版本不存在 wx.loadSubpackage 方法。

已知 BUG

目前 Android 无法加载分包下的字体文件，预计在下个微信客户端版本修复。

LoadSubpackageTask wx.loadSubpackage(Object object)

基础库 2.1.0 开始支持，低版本需做兼容处理

触发分包加载，详见 分包加载

参数

Object object

返回值

LoadSubpackageTask

加载分包任务实例，用于获取分包加载状态

LoadSubpackageTask.onProgressUpdate(function callback)

基础库 2.1.0 开始支持，低版本需做兼容处理

监听分包加载进度变化事件

参数

callback

监听事件的回调函数

callback 回调函数

参数

res