目录

分包是什么？

为什么要分包？

分包前后结构对比

具体操作步骤

第 1 步：规划分包结构

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

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

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

第 5 步：重新编译并测试

进阶概念：独立分包

注意事项

已通过效果：

---

分包是什么？

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

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

• 主包：包含小程序启动所需的核心页面（如首页、TabBar 页面）和所有分包都会用到的公共代码/资源。

• 分包：包含某些特定功能下的页面、组件、代码和资源。用户在使用到这些功能时才会下载对应的分包。

为什么要分包？

1. 突破体积限制：小程序单个包体积限制为 2MB。使用分包后，整个小程序所有分包的总体积上限可提升至 20MB（微信小程序目前标准）。（目前一个包超过1.5mb就会提示了）

2. 优化启动速度：小程序启动时只需下载主包（通常很小），用户点击进入某个分包页面时，才去下载对应的分包代码。这大大降低了首屏加载时间。

3. 按需加载：只有用户真正访问到某个功能时，才加载对应的代码，节省了用户流量和空间。

---

分包前后结构对比

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

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

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

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。

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

注意事项

1. TabBar 页面：必须放在主包中，不能在分包中定义。

2. 公共代码：所有分包都会用到的 JS 库、自定义组件、样式等，尽量放在主包中。

3. 主包体积：要时刻关注主包的大小（开发者工具详情页可查看），因为它直接影响启动速度。主包最好控制在 1.5MB 以内，预留一些空间。

4. 分包之间的跳转：

   • 跳转到分包页面：wx.navigateTo({ url: '/packageA/pages/category/category' })

   • url 路径必须以分包根目录 root 开头。

5. 引用原则：

   • 分包可以引用自己包内的组件和工具。

   • 分包可以引用主包内的组件和工具。

   • 分包不能引用其他分包内的文件。

   • 主包不能引用分包内的文件。

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

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

   已通过效果：