tencent cloud

分包加载
下载PDF
最后更新时间：2025-02-24 17:10:40
分包加载
最后更新时间： 2025-02-24 17:10:40
下载PDF
随着小游戏的玩法越来越丰富，开发者对于扩大包大小的需求越来越强烈，所以我们推出了小游戏分包加载这一个功能。所谓的分包加载，即把游戏内容按一定规则拆分这几包，在首次启动时先下载必要的包，这个必要的包我们称为主包，开发者可以在主包内触发其它分包的下载，从而把首次启动的下载耗时分散到游戏运行中。
开发者可以使用框架封装的分包加载能力，也可以在不使用框架的情况下直接使用 game.json 配置分包，相关详情如下。

使用限制

目前小游戏分包大小有以下限制：
整个小游戏所有主包+分包大小不超过 20M
主包不超过 4M
单个普通分包不限制大小
单个独立分包不超过 4M

使用分包

配置方法

假设游戏的目录结构如下：
├── game.js
├── game.json
├── images
│   ├── a.png
│   ├── b.png
├── stage1
│   └── game.js
│   └── images
│       ├── 1.png
│       ├── 2.png
└── stage2.js
└── utils
game.json 中的配置：
{
  ...
  "subpackages": [
    {
      "name": "stage1",
      "root": "stage1/" // 可以指定一个目录，目录根目录下的 game.js 会作为入口文件，目录下所有资源将会统一打包
    }, {
      "name": "stage2",
      "root": "stage2.js" // 也可以指定一个 JS 文件
    }
  ]
  ...
}
subpackages 中，每个分包的配置有以下几项：
字段
类型
说明
root
String
分包根目录
name
String
分包别名，分包预下载时可以使用
independent
Boolean
分包是否是独立分包

打包原则

声明 subpackages 后，将按 subpackages 配置路径进行打包，subpackages 配置路径外的目录将被打包到主包中。
subpackage 的根目录不能是另外一个 subpackage 内的子目录。

引用原则

packageA 无法 require packageB JS 文件，但可以 require 主包、packageA 内的 JS 文件。
packageA 无法使用 packageB 的资源，但可以使用主包、packageA 内的资源。

独立分包

独立分包是小游戏中一种特殊类型的分包，可以独立于主包和其他分包运行。以独立分包路径启动小游戏时，客户端会仅下载独立分包并启动游戏，不会下载主包，以此实现部分场景下快速启动游戏的需求。开发者可以按需将某些具有一定功能独立性的页面配置到独立分包中，可以很大程度提高页面打开速度。
独立分包启动后，开发者可以按需使用wx.loadSubpackage接口预下载主包或其他分包，并在合适时机（例如用户点击开始游戏时）执行已下载的代码包逻辑。

配置方法

假设小游戏目录结构如下：
.
├── game.js
├── game.json
├── moduleA
│   └── game.js
├── moduleB
│   └── game.js
└── utils
开发者通过在game.json的subpackages字段中对应的分包配置项中定义independent字段声明对应分包为独立分包。
{
  "subPackages": [
    {
      "name": "moduleA",
      "root": "/moduleA/", // 普通分包
    },
    {
      "independent": true, // 独立分包，指定一个目录，目录根目录下的 game.js 会作为入口文件，目录下所有资源将会统一打包
      "name": "moduleB",
      "root": "/moduleB/",
    }
  ]
}
游戏内分享指定独立分包页面：
// 分享给好友、群
wx.shareAppMessage({
  title: '分享标题',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path 为 game.json 配置中独立分包的 root
})
// 分享到朋友圈
wx.onShareTimeline({
  title: '分享标题',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path 为 game.json 配置中独立分包的 root
})
// 添加到收藏
wx.addToFavorites({
  title: '收藏标题',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path 为 game.json 配置中独立分包的 root
})
独立分包内，下载其他分包：
const loadTask = wx.loadSubpackage({
  name: '/moduleA/', // 下载其他分包
  success(res) {
    console.log('load moduleA success', res)
  },
  fail(err) {
    console.error('load moduleA fail', err)
  }
})

注意事项

一个小游戏中可以有多个独立分包。
小游戏独立分包启动只对冷启动有效。
独立分包属于分包的一种。普通分包的所有限制都对独立分包有效。
独立分包中不能依赖主包和其他分包中的内容，包括 JS 文件和资源文件。
wx.shareAppMessage参数或wx.onShareAppMessage回参中的path必须是game.json中定义的独立分包的root字段。

分包加载

我们提供了 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)
})

分包预加载

我们提供了 wx.preDownloadSubpackage() API 来触发分包的预下载，调用 wx.preDownloadSubpackage 后，将触发分包的下载与加载，在加载完成后，通过 wx.preDownloadSubpackage 的 success 回调来通知加载完成。预加载完成后，需要使用 wx.loadSubpackage 执行分包代码。
wx.preDownloadSubpackage() 与 wx.loadSubpackage() 的区别：wx.preDownloadSubpackage 只下载代码包，不自动执行代码；wx.loadSubpackage 下载完代码包后会自动执行代码。

示例代码：
// 预加载
const loadTask = wx.preDownloadSubpackage({
  name: 'stage1',
  success: function(res) {
    // 分包预加载成功后通过 success 回调
  },
  fail: function(res) {
    // 分包预加载失败通过 fail 回调
  }
})

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

// 在合适的时机执行分包代码逻辑
wx.loadSubpackage({
  name: 'stage1'
})

本页内容是否解决了您的问题？
您也可以 联系销售 或 提交工单 以寻求帮助。
是
否

文档反馈