使用建议：用于共享可以被复用的能力单元。开发者可以按需将“通用”且“非启动时强依赖” 的能力放到通用分包中；可以通过异步引用方式使用通用分包的资源（仅提供支持 JS, 自定义组件异步使用方式），通用分包可以有效解决主包过大的问题。一个小程序中可以有多个通用分包（为避免多次下载包影响运行性能，建议放到一个通用分包中）。

与普通分包差异：

•

需要额外字段标识，类似独立分包的 independent，通用分包需要标识 common: true。

•

可以被其他分包引用。

•

pages 字段为空或不配置（即仅允许提供通用能力：JS、自定义组件）。

配置示例

假设支持分包的小程序，目录结构如下：

├── app.js
├── app.json
├── app.ttss
├── packageA
│   └── pages
│       ├── pageOne
│       └── pageTwo
├── packageB
│   └── components
│       ├── component1
│       └── component2
├── pages
│   ├── index
│   └── logs
└── utils

开发者通过在 app.json 的 subpackages 字段中对应的分包配置项中定义 common 字段声明对应分包为通用分包。

示例：配置 packageB 为通用分包：

{ 
  "pages": ["pages/index", "pages/logs"],
  "subpackages": [
    {
      "root": "packageA",
      "pages": ["pages/pageOne", "pages/pageTwo"]
    },
    {
      "root": "packageB",
      "pages": [],
      "common": true
    }
  ]
}

使用限制

通用分包属于分包的一种。普通分包的所有限制都对通用分包有效。通用分包中自定义组件的处理方式同普通分包。此外，使用通用分包时要注意：

•

通用分包 pages 字段为空或不配置（即仅允许提供通用能力-JS-自定义组件）。

•

通用分包中的资源只能通过异步引用方式被引用，目前仅支持自定义组件（结合占位组件使用）、JS 文件。

•

不支持 template、ttss、sjs、图片资源的异步引用。

•

单个分包大小不能超过 2M。

引用通用分包的自定义组件

一个分包使用其他分包的自定义组件时，由于其他分包还未下载或注入，其他分包的组件处于不可用的状态。通过为其他分包的自定义组件设置占位组件，我们可以先渲染占位组件作为替代，在页面主要内容渲染完成后下载分包并替换。

例如：主包/分包内引用通用分包自定义组件：

{ 
  "usingComponents": {
    "button": "/commonPackageA/components/com1/com1"
  },
  "componentPlaceholder": {
    "button": "view"
  }
}

在这个配置中，custom-button 自定义组件是跨分包引用组件， custom-button 在渲染时会使用内置组件 view 作为替代；在页面主要元素渲染完成后会下载 commonPackageA 分包，占位组件就会被替换为对应的跨分包组件。

可以使用 tt.onLazyLoadError 监听加载事件。

引用通用分包的 JS

一个分包中的代码引用其它分包的代码时，为了不让下载阻塞代码运行，我们需要异步获取引用的结果。

require 能力使用介绍：require 引入模块。返回模块通过 module.exports 或 exports 暴露的接口。需要引入其他分包的模块的时候，可以通过配置 callback 回调函数来异步获取指定模块。异步获取失败的时候，将会触发 error 回调函数。或者通过 require.async 方式调用，返回值为 promise。

callback 方式

语法

require(path, successCallback, errorCallback);

参数说明

属性名	类型	必填	说明	最低支持版本
path	string	是	需要引入模块文件相对于当前文件的相对路径，或npm模块名，或 npm 模块路径。默认不支持绝对路径。	1.0.0
successCallback	function	否	异步加载成功回调函数，该回调函数参数为成功加载的模块。使用异步 require 能力时该参数必填。不写表示同步引用	2.86.1
errorCallback	function	否	异步加载失败回调函数，该回调函数参数为错误信息和模块名。	2.86.1

errorCallback 参数 object 类型，属性如下：

属性名	类型	说明	最低支持版本
mod	string	传入的路径信息	2.86.1
errMsg	string	错误详情	2.86.1

返回值

同步调用 require 返回值为执行结果；异步方式调用（有合法的 successCallback）没有返回值。

代码示例

require("common.js", (res) => {
  console.log("加载成功", res);
}, (err) => {
  console.warn("加载失败", err);
});

require.async 方式

也可以通过 require.async 链式调用的方式使用。

语法

require.async(path);

参数说明

属性名	类型	必填	说明	最低支持版本
path	string	是	需要引入模块文件相对于当前文件的相对路径，或 npm 模块名，或 npm 模块路径。默认不支持绝对路径。	2.86.1

返回值

promise 类型。catch 到的 error 类型，object，属性如下：

属性名	类型	说明	最低支持版本
mod	string	传入的路径信息	2.86.1
errMsg	string	错误详情	2.86.1

代码示例

require 
  .async("common.js")
  .then((res) => {
    console.log("加载成功", res);
  })
  .catch((res) => {
    console.warn("加载失败", err);
  });

Bug & Tip

Tip：相关能力：占位组件、tt.onLazyLoadError、tt.offLazyLoadError。