• 下载
  • 社区

分包加载

版本要求:基础库 1.14.0 或更高版本;支付宝客户端 10.1.60 或更高版本,若版本较低,建议做 兼容处理;小程序开发者工具 0.40 或更高版本。

为了满足日益复杂的小程序业务需求,同时提升首次打开速度,支付宝小程序从客户端 10.1.60 版本开始支持分包加载功能。

开发者可以按需将小程序划分为若干个不同的子包。小程序使用分包功能时,会默认有一个主包,启动页面和 tabBar 所有页面都放在主包中,同时包含了小程序所需的公共资源(例如 js 脚本等)。在服务端构建时,会根据开发者的配置,打成不同的分包,用户在使用小程序进入对应分包的页面时,客户端会下载该分包,并进行解析和渲染。

使用建议

  • 对体积较大的小程序项目,建议使用此功能。
  • 主包只保留最常用的核心页面(首页、tabBar 页面和其他公共资源),将小程序中不经常使用的页面放到多个分包中,启动时只加载主包,使用时按需下载分包,不要一次性下载整个代码包,以提升首页启动速度。
  • 对于经常会访问到的待跳转页面,尽可能将该页面所在的分包配置成分包预下载,以提升页面跳转速度。
  • 如果小程序由不同的团队协作开发,建议使用此功能。

使用方法

配置方法

典型的分包小程序目录如下:

├── app.acss
├── app.js
├── app.json
├── packageA
│   └── pages
│       ├── page1
│       └── page2
├── packageB
│   └── pages
│       ├── page3
│       └── page4
└── pages
    ├── common
    └── index

开发者在 app.json 文件的 subPackages 字段中声明小程序的分包结构:

{
  "pages": [
    "pages/index",
    "pages/common"
  ],
  "subPackages": [
    {
      "root": "packageA",
      "pages": [
        "pages/page1",
        "pages/page2"
      ]
    },
    {
      "root": "packageB",
      "pages": [
        "pages/page3",
        "pages/page4"
      ]
    }
  ]
}

subPackages 字段的配置说明如下:

字段 类型 说明
root String 分包根目录
pages StringArray 分包页面路径

打包与引用原则

  • 开发者配置 subPackages 后,服务端将按 subPackages 配置的路径进行打包,subPackages 配置路径外的目录将被默认打包到主包中。
  • 启动页面和 tabBar 的所有页面都必须放在主包中。
  • 每个分包的根目录不能是另外一个分包内的子目录。
  • 分包之间不能相互引用对方包中的资源(比如图片和 js 脚本等),分包可以引用主包和自己包内的资源。
  • 分包和主包是分别独立打包的,同一个js模块会在主包和分包中分别存在。

分包大小限制

  • 整个小程序所有分包大小不超过 4MB。
  • 单个分包或主包大小不能超过 2MB。

低版本兼容

支付宝服务端构建平台负责处理低版本客户端的兼容,服务端会编译并打包成两份源码包,一份是分包后的代码包,另一份是整包的兼容代码包。支持分包的新客户端使用分包,不支持分包的低版本客户端使用整包。

分包预下载

开发者可以通过在 app.json 里的 preloadRule 字段进行配置,在进入小程序某个页面时,由框架自动下载可能需要的分包,以提升分包页面的启动速度。

一个典型的分包预加载配置如下:

{
  "pages": ["pages/index"],
  "subPackages": [
    {
      "root": "sub1",
      "pages": ["page1"]
    },
    {
      "root": "sub2",
      "pages": ["page2"]
    },
    {
      "root": "sub3",
      "pages": ["page3"]
    },
    {
      "root": "path/sub4",
      "pages": ["page4"]
    }
  ],
  "preloadRule": {
    "pages/index": {
      "network": "all",
      "packages": ["sub1"]
    },
    "sub1/page1": {
      "packages": ["sub2", "sub3"]
    },
    "sub3/page3": {
      "network": "wifi",
      "packages": ["path/sub4"]
    }
  }
}

preloadRule 字段中,key 是页面路径,value 是进入此页面后预下载的配置,每个配置的选项说明如下:

字段 类型 是否必须 默认值 说明
packages StringArray 进入页面后预下载的分包的 root
network String all 在指定网络下进行预下载,all:不限网络;wifi:仅 wifi 下预下载

常见问题

Q:小程序超过大小限制,应该分包还是减少模块?
A:小程序最大限制是2M,如果超过了可以进行代码优化,把一些图片放到服务器中来减小包的大小。如果实在没法控制,可以使用小程序分包。