《十六》微信小程序中的分包

原创已于 2025-03-08 08:58:29 修改 · 7.8k 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#微信小程序

于 2021-04-02 18:39:17 首次发布

微信小程序专栏收录该内容

35 篇文章

订阅专栏

微信小程序允许开发者将其划分为主包和多个分包，以优化启动时间和团队协作。主包包含默认启动页面和公共资源，分包按需加载。分包预下载和独立分包特性进一步提高用户体验。分包异步化则解决了跨分包组件和JS代码的依赖问题。配置分包预下载规则和使用组件占位符可确保流畅运行。

某些情况下，开发者需要将小程序划分成不同的子包，在构建时打包成不同的分包，用户在使用时按需进行加载。对小程序进行分包，可以优化小程序首次启动的下载时间，以及在多团队共同开发时可以更好的解耦协作。

在小程序启动时，默认会下载主包并启动主包内页面；当用户进入分包内某个页面时，客户端会把对应分包下载下来，下载完成后再进行展示。

目前小程序分包大小有以下限制：整个小程序所有分包大小不超过 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}`)
})