支付宝小程序框架分包加载

版本要求：基础库 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模块会在主包和分包中分别存在。

分包大小限制

整个小程序所有分包大小不超过 8MB。
单个分包或主包大小不能超过 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，如果超过了可以进行代码优化，把一些图片放到服务器中来减小包的大小。如果实在没法控制，可以使用小程序分包。

支付宝小程序框架 分包加载