微信小程序如何进行分包处理？

分包是什么？

为什么要分包？

分包前后结构对比

具体操作步骤

[第 1 步：规划分包结构](#第 1 步：规划分包结构)

[第 2 步：修改 app.json 进行配置](#第 2 步：修改 app.json 进行配置)

[第 3 步：创建分包目录并移动文件](#第 3 步：创建分包目录并移动文件)

[第 4 步：处理组件和工具函数的引用](#第 4 步：处理组件和工具函数的引用)

[第 5 步：重新编译并测试](#第 5 步：重新编译并测试)

进阶概念：独立分包

注意事项

已通过效果：

分包是什么？

一说到这个其实好多人就想骂了，先附上几张图（不忍直视）：

小程序分包是指将完整的小程序项目划分成一个主包 和多个分包。

主包：包含小程序启动所需的核心页面（如首页、TabBar 页面）和所有分包都会用到的公共代码/资源。
分包：包含某些特定功能下的页面、组件、代码和资源。用户在使用到这些功能时才会下载对应的分包。

为什么要分包？

突破体积限制 ：小程序单个包体积限制为 2MB。使用分包后，整个小程序所有分包的总体积上限可提升至 20MB（微信小程序目前标准）。（目前一个包超过1.5mb就会提示了）
优化启动速度 ：小程序启动时只需下载主包（通常很小），用户点击进入某个分包页面时，才去下载对应的分包代码。这大大降低了首屏加载时间。
按需加载：只有用户真正访问到某个功能时，才加载对应的代码，节省了用户流量和空间。

分包前后结构对比

举例一个电商小程序，结构如下：

（看完下面这个，我敢说基本上都能懂了，是不是简简单单？哈哈）

分包前（所有内容都在主包）：

project-root/
├── app.js
├── app.json
├── app.wxss
├── pages/
│ ├── index/ # 首页 (TabBar)
│ ├── logs/ # 日志页 (TabBar)
│ ├── category/ # 分类页
│ ├── product/ # 商品详情页
│ └── profile/ # 个人中心页
├── components/
│ ├── header/ # 公共头部组件
│ └── toast/ # 公共弹窗组件
└── utils/
└── request.js # 公共网络请求库

分包后（按功能拆分）：

project-root/
├── app.js
├── app.json
├── app.wxss
├── pages/ # 【主包】主要页面
│ ├── index/ # 首页 (TabBar，必须放主包)
│ ├── logs/ # 日志页 (TabBar，必须放主包)
│ └── profile/ # 个人中心页
├── components/ # 【主包】公共组件
│ ├── header/
│ └── toast/
├── utils/ # 【主包】公共工具库
│ └── request.js
│
├── packageA/ # 【分包A】商品模块
│ ├── packageA.json # 分包A的配置文件
│ ├── pages/
│ │ ├── category/ # 分类页
│ │ └── product/ # 商品详情页
│ └── components/ # 分包A专用的组件
│ └── product-card/
│
└── packageB/ # 【分包B】未来可能扩展的模块
├── packageB.json
└── pages/
└── cart/ # 购物车页

具体操作步骤

第 1 步：规划分包结构

确定哪些页面是启动就必须的（放主包），哪些功能可以独立成模块（放分包）。TabBar 页面必须在主包。

第 2 步：修改 `app.json` 进行配置

在 app.json 中新增 subpackages 或 subPackages（两者均可）字段来声明分包。

复制代码

// app.json
{
  "pages": [
    "pages/index/index",
    "pages/logs/logs",
    "pages/profile/profile" // 主包页面
  ],
  "subPackages": [
    {
      "root": "packageA", // 分包的根目录名
      "name": "shop", // 分包的别名，用于分包异步化时引用，可省略
      "pages": [ // 分包内的页面路径，相对于 root 根目录
        "pages/category/category",
        "pages/product/product"
      ],
      "independent": false // 是否为独立分包（默认为 false）
    },
    {
      "root": "packageB",
      "pages": [
        "pages/cart/cart"
      ]
    }
  ],
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index" // TabBar 页面必须在主包
      },
      {
        "pagePath": "pages/logs/logs" // TabBar 页面必须在主包
      }
    ]
  },
  // ... 其他 window 等配置
}

第 3 步：创建分包目录并移动文件

根据你在 app.json 中的配置，在项目根目录创建分包文件夹（如 packageA），然后将对应的页面、组件、资源文件移动到这个文件夹下。

重要： 移动文件后，一定要修改 app.json 中对应的路径。原来在主包 pages 里声明的分包页面路径要删除。

第 4 步：处理组件和工具函数的引用

公共组件/工具（如 utils/request.js） ：继续放在主包，所有分包都可以直接 require 或 import。
分包内私有组件/工具：放在分包目录下，只能被该分包内的页面引用。

第 5 步：重新编译并测试

在微信开发者工具中点击编译，检查是否有路径错误。然后通过右上角的"编译模式"，选择"添加编译模式"，单独测试每一个分包页面，确保能正常加载和显示。

进阶概念：独立分包

独立分包是分包的一种特殊类型，可以独立于主包运行，不需要下载主包。

特点：通常用于某些广告页、活动页等上下文独立性极强的页面。用户从独立分包页面进入小程序时，不需要下载主包，速度极快。
限制：独立分包不能引用主包内的任何文件（公共组件、工具库都不行）。
配置：将 independent 属性设为 true。

javascript 复制代码

// app.json
{
  "subPackages": [
    {
      "root": "independentModule",
      "pages": ["pages/promotion/promotion"],
      "independent": true // 声明为独立分包
    }
  ]
}

注意事项

TabBar 页面 ：必须放在主包中，不能在分包中定义。
公共代码：所有分包都会用到的 JS 库、自定义组件、样式等，尽量放在主包中。
主包体积 ：要时刻关注主包的大小（开发者工具详情页可查看），因为它直接影响启动速度。主包最好控制在 1.5MB 以内，预留一些空间。
分包之间的跳转：
- 跳转到分包页面：wx.navigateTo({ url: '/packageA/pages/category/category' })
- url 路径必须以分包根目录 root 开头。
引用原则：
- 分包可以引用自己包内的组件和工具。
- 分包可以引用主包内的组件和工具。
- 分包不能引用其他分包内的文件。
- 主包不能引用分包内的文件。

分包预加载：可以使用 preloadRule 配置在进入主包某个页面时，静默预加载可能即将用到的分包，提升后续跳转流畅度。

javascript 复制代码

// app.json
"preloadRule": {
  "pages/index/index": { // 当用户从首页启动时
    "network": "all", // 在任意网络下都预加载
    "packages": ["packageA"] // 预加载 packageA 分包
  }
}