1.什么是分包：

    微信分包是微信小程序开发中一种优化策略，目的是解决小程序代码包体积超过微信平台限制（主包最大为2MB，分包单个最大为2MB，总体不超过20MB）的情况。

具体来说：

主包与分包
微信小程序的代码被分为主包和分包。

1.主包：用户启动小程序时必须加载的内容（如首页、基础功能）。

2.分包：用户后续访问才需要加载的功能模块，按需下载，降低初次加载时间。

优势与意义：
降低启动时的加载量：减少用户打开小程序时加载的数据量，提升启动速度和用户体验。
按需加载：用户只下载访问到的功能模块，避免一次性下载不必要的内容。
突破包体积限制：通过分包方式，整体可容纳更多内容或更复杂的功能。

1.1分包的好处：

1. 缩短首次加载时间

  主包体积更小，用户首次打开小程序时只需加载最基本的页面和功能，加载速度更快，提升用户体验。

2. 减少资源浪费

  用户仅下载实际访问的功能模块，避免加载未使用的内容，降低带宽消耗，提高加载效率。

3. 突破包体积限制

  微信小程序主包体积限制为2MB，单个分包也限制为2MB，总体不超过20MB。通过分包可以容纳更丰富的功能和内容，扩展小程序的规模。

4. 灵活功能管理

  不同功能模块独立开发、维护和升级，方便团队协作，且不会相互干扰，代码结构更清晰。

5. 提升用户体验

  用户只下载必要资源，减少等待时间，交互体验更流畅，降低用户流失率。

6. 便于扩展和维护

  随着小程序功能增加，可以更容易地进行模块化管理，便于后期维护和功能扩展，降低开发成本和复杂度。

1.2分包前的构成 

在进行微信小程序分包之前，小程序的构成是一个完整的主包，所有页面和资源都包含在这个主包中，导致整个项目体积过大，影响小程序首次启动的下载时间。

1. 单一主包结构

项目根目录/
├── app.js                // 小程序逻辑
├── app.json              // 配置所有页面（都在主包中）
├── app.wxss              // 全局样式
├── pages/                // 所有页面
│   ├── index/
│   │   ├── index.js
│   │   ├── index.json
│   │   ├── index.wxml
│   │   └── index.wxss
│   ├── mine/
│   └── settings/
├── utils/                // 公共方法
└── images/               // 图片资源

2. 页面集中配置

所有页面路径都统一写在 app.json 的 pages 数组中，例如：

"pages": [
  "pages/index/index",
  "pages/mine/index",
  "pages/settings/index"
]

 1.3分包后的构成 

分包后，微信小程序的项目构成从单一主包变成了主包 + 一个或多个分包的结构。每个分包是一个相对独立的功能模块，只有在访问对应页面时才会被加载。

主包：一般只包含项目的启动页面或TabBar页面、以及所有分包都需要用到的一些公共资源

分包：只包含和当前分包有关的页面和私有资源

分包后的项目构成

项目根目录/
├── app.js
├── app.json                // 主包页面 + 分包配置
├── app.wxss
├── pages/                  // 主包页面（如首页、登录页）
│   └── index/
│       ├── index.js
│       ├── index.wxml
│       ├── index.json
│       └── index.wxss
├── packageA/               // 分包 A
│   └── page1/
│       ├── index.js
│       ├── index.wxml
│       ├── index.json
│       └── index.wxss
├── packageB/               // 分包 B
│   └── page2/
│       └── ...
├── utils/                  // 公共代码
└── images/

配置示例

{
  "pages": [
    "pages/index/index"        // 主包页面（必须）
  ],
  "subPackages": [
    {
      "root": "packageA",      // 分包路径
      "pages": [
        "page1/index"
      ]
    },
    {
      "root": "packageB",
      "pages": [
        "page2/index"
      ]
    }
  ]
}

 1.4分包的加载规则

1.在小程序启动时，默认会下载主包并启动主包内页面
      tabBar 页面需要放到主包中
2.当用户进入分包内某个页面时，客户端会把对应分包下载下来，下载完成后再进行展示
      非 tabBar 页面可以按照功能的不同，划分为不同的分包之后，进行按需下载

1.5分包的限制 

1.整个小程序所有分包大小不超过20M（主包+所有分包）

2.单个分包/主包大小不能超过2M

类型	限制说明
主包体积	≤ 2MB（含页面、样式、JS、资源等）
单个分包体积	≤ 2MB
所有包总体积	≤ 20MB（主包 + 所有分包总和）

如果体积超过，将无法上传或通过审核。


结构限制

规则	说明
subPackages 必须配置在 app.json 顶层	不支持动态配置
所有分包目录必须平级存在	不支持嵌套分包（即不能在分包里再定义分包）
分包只能访问自己内部资源	无法访问其他分包的私有资源
tabBar 页面必须在主包中	禁止将 tabBar 页面放入分包
分包页面路径不能写错	路径需相对于分包 root，且结构必须清晰一致
主包不能引用分包资源	否则运行时报错或构建失败
独立分包不能依赖主包资源	必须自带运行环境（如 app.js、app.json）

引用限制

场景	是否允许	说明
分包访问主包资源	✅	可以（如公用组件、JS）
主包访问分包资源	❌	不允许
分包访问另一个分包资源	❌	不允许
独立分包访问主包或其他分包	❌	不允许
分包使用主包组件/样式	✅	路径正确即可，适合放公用资源

数量限制（2024年起）

项目	限制值
最大分包数量	150 个（早期为 10 个，已放宽）
每个分包最大页面数	建议 < 50（非强制）

调试&编译限制

• 分包路径写错或结构不清晰，微信开发者工具会报错

• app.json 中配置顺序/缩进错误，也可能导致分包失效

• 一些插件、第三方库在分包中引用时需注意路径是否兼容

总结：“主包必须小，分包各自跑，路径别乱跳，tabBar归主包。”

2.使用分包

2.1配置方法

在app.json 的 subpackages 节点中声明分包的结构，示例代码如下：

{
    //主包的所有页面
    "pages":[
        "pages/index",
        "pages/logs"
    ],
    //通过subpackages节点，声明分包的结构
    "subpackages":[
        {
            //第一个分包的根目录
            "root":"packageA",
            //当前分包下，所有页面的相对存放路径
            "pages":[
                "pages/cat",
                "pages/dog"
            ]
        },{
            //第二个分包的根目录
            "root":"packageB",
            //当前分包下，所有页面的相对存放路径
            "pages":[
                "pages/apple",
                "pages/banana"
            ]
        }
    ]
}

2.2打包原则 

① 小程序会按 subpackages 的配置进行分包，subpackages 之外的目录将被打包到主包中

• 解释：app.json 中通过 subpackages 配置的路径，会被微信识别为独立分包；除此之外的所有资源（如 pages/、utils/、components/ 等默认目录）会自动打入主包。

• 注意：放在主包的资源也要控制体积（≤2MB），否则无法通过上传和发布。

② 主包也可以有自己的 pages（即最外层的 pages 字段）

• 解释：app.json 顶层的 "pages" 字段就是主包页面的配置区域，这些页面在小程序启动时会优先加载。

• 使用场景：通常放首页、登录页、欢迎页等启动必须页面。

  "pages": [
    "pages/index/index",    // 属于主包
    "pages/login/login"
  ]
  

③ tabBar 页面必须在主包内

• 解释：微信官方要求，配置在 tabBar 中的页面必须在主包中，不能放在任何分包内。

• 原因：tabBar 是小程序的全局导航入口，系统需要在小程序启动阶段立即加载，分包无法满足实时性。

• 报错示例：如果你将 tabBar 页面放在分包中，会提示“tabBar 页面必须在主包中”。

④ 分包之间不能互相嵌套

• 解释：不能在一个分包目录下再放另一个分包；也不能在一个分包内跳转到另一个分包的页面（除非先跳回主包）。

• 正确做法：所有分包都应该直接在项目根目录下平级配置，例如：

  "subpackages": [
    {
      "root": "packageA",
      "pages": ["a1", "a2"]
    },
    {
      "root": "packageB",
      "pages": ["b1", "b2"]
    }
  ]
  

  总结：

• ①	未配置的目录归主包	默认打包到主包
  ②	主包通过 pages 配置自己的页面	pages 主包
  ③	tabBar 只能放主包	tabBar 主包强制
  ④	分包结构必须扁平	不支持嵌套

2.3引用原则

① 主包无法引用分包内的私有资源

• 解释：主包中的代码（如页面、组件、JS工具）不能访问任何只存在于某个分包内的资源。

• 原因：分包是按需异步加载的，主包启动时并未加载分包，引用会报错。

② 分包之间不能相互引用私有资源

• 解释：一个分包内的页面或组件不能直接引用另一个分包的资源。

• 原因：微信分包是封闭式结构，每个分包独立存在，彼此不可见。

③ 分包可以引用主包内的公共资源

• 解释：分包中的页面或组件可以使用主包中声明的公共资源（如工具类、样式、公共组件）。

• 要求：路径要正确、主包中资源需在小程序启动时可用。

总结：主包看不到分包，分包看不到彼此，但都能看主包。

 

3.独立分包

3.1什么是独立分包

独立分包是微信小程序的一种特殊分包形式，它可以脱离主包独立运行，即在不加载主包的情况下就能直接启动和使用。

3.2独立分包和普通分包的区别

最主要的区别：是否依赖于主包才能运行

1.普通分包必须依赖于主包才能运行

2.独立分包可以在不下载主包的情况下，独立运行

3.3独立分包的应用场景 

开发者可以按需，将某些具有一定功能独立性的页面配置到独立分包中。原因如下：

1.当小程序从普通的分包页面启动时，需要首先下载主包

2.而独立分包不依赖主包即可运行，可以很大程度上提升分包页面的启动速度

注意：一个小程序中可以有多个独立分包。

3.4 独立分包的配置方法

小程序的目录结构，如下图所示：

通过independent声明独立分包，代码如下所示：

{
    "pages":[
        "pages/index",
        "pages/logs"
    ],
    "subpackages":[
        {
            
            "root":"moduleA",//moduleA为普通分包
            "pages":[
                "pages/rabbit",
                "pages/squirrel"
            ]
        },{
            "root":"moduleB",
            "pages":[
                "pages/pear",
                "pages/pineapple"
            ],
       "independent":true     //通过此节点，声明当前moduleB分包为“独立分包”
            
        }
    ]
}

3.5引用原则

微信小程序中独立分包的引用原则有别于普通分包，主要体现在资源隔离性更强、依赖更严格。你可以理解为一个“完全自给自足”的小程序单元，它不能依赖主包资源，也不能访问其他分包。

独立分包和普通分包以及主包之间，是相互隔绝的，不能相互引用彼此的资源！例如：

① 主包无法引用独立分包内的私有资源

② 独立分包之间，不能相互引用私有资源

③ 独立分包和普通分包之间，不能相互引用私有资源

④ 特别注意：独立分包中不能引用主包内的公共资源

独立分包的引用原则总结如下：

编号	原则内容	是否允许	说明
①	独立分包可以访问其内部的页面、组件、资源	✅	正常使用，需路径正确
②	独立分包❌不能访问主包中的任何资源（JS、样式、组件等）	❌	包括 utils、公共组件、图片等
③	独立分包❌不能访问其他分包的资源	❌	所有引用必须是本分包私有
④	主包也❌不能访问独立分包的资源	❌	独立分包资源只能内部使用
⑤	独立分包内必须包含自己的 app.js、app.json、app.wxss（简化版）	✅	用于提供基础运行能力，类似“局部主包”

图示结构对比

注意：分包路径引用不能使用主包内的 utils/、components/ 等内容，哪怕路径写得对也会在构建或运行时报错。

项目根目录/
├── app.js                      ← 主包逻辑
├── app.json                    ← 主包配置
├── pages/                      ← 主包页面
├── packageUser/                ← 独立分包
│   ├── app.js                  ← 独立运行的逻辑
│   ├── app.json                ← 配置分包页面
│   ├── app.wxss                ← 分包样式（可省略）
│   └── pages/
│       ├── login/
│       └── profile/

 总结：独立分包必须独立生活，不能伸手向外要资源。

4.分包预下载

4.1什么是分包预下载

分包预下载指的是：在进入小程序的某个页面时，由框架自动预下载可能需要的分包，从而提升进入后续分包页面时的启动速度。

4.2配置分包的预下载

{
    
    "preloadRule":{//分包预下载的规则
        
        "pages/contact/contact":{//触发分包预下载的页面路径
            //network 表示在指定的网络模式下进行预下载，
            //可选值为：all(不限网络)和wifi（仅wifi模式下进行预下载）
            //默认值为:wifi
            "network":"all",
            //packages表示进入页面后，预下载哪些分包
            //可以通过root或name指定预下载哪些分包
            "packages":["packageA"]
        }
    }
}

注意事项：

• 只能预下载分包，不能预下载主包。

• 绑定页面必须是主包页面。

• "packages" 的值必须与 subPackages.root 保持一致。

• 包体积限制仍然有效（单个 ≤2MB，总体 ≤20MB）。

 4.3分包预下载的限制

1.只能预下载分包，不能预下载主包

• 你只能预加载通过 subPackages 配置的分包。

• 主包不支持预下载（主包必须在小程序启动时加载完毕）。

2.预下载仅在访问指定页面时触发

必须绑定在 app.json 中指定的页面（如主包页面），在访问该页面时才会开始预下载。

"preloadRule": {
  "pages/index/index": {
    "network": "all",
    "packages": ["packageA"]
  }
}

不能动态触发预下载，只能通过静态配置。

3.路径必须与 subPackages.root 对应

• "packages" 中填写的必须是你在 subPackages 里定义的 root 名称。

• 否则预下载不会生效，且不会报错，容易漏查。

4.受网络条件限制

• "network" 可选值：

  • "all"：在任何网络环境下都触发预下载；

  • "wifi"：仅 Wi-Fi 环境下才触发；

• 在 "wifi" 模式下，如果用户是 4G 或 5G 网络，则不会预下载。

5. 包体积限制仍然有效

单个分包	≤ 2MB
总体积限制	主包 + 所有分包 ≤ 20MB（预下载不突破限制）

6. 预下载是异步后台操作，不会阻塞当前页面

• 它并不影响当前页面加载，只是提前“悄悄下载”指定分包。

• 如果用户跳转太快（还没下完），仍然会等待分包下载完成。

7. 不能配置到分包内页面上

"preloadRule" 只能绑定在 主包页面上，不能配置在分包的页面路径。

总结：“预的是分包，不是主包；绑主包页面，走后台下载；路径要对，网络有限。”