微信小程序分包

一、前言

随着微信小程序功能的不断扩展，代码体积也逐渐增大。而微信小程序对 主包大小限制为 2MB（压缩后），超过这个限制将无法上传发布。

为了解决这一问题，小程序分包机制 应运而生 —— 它允许我们将一个大型小程序拆分为多个子包，按需加载，从而突破大小限制并提升首屏加载速度。

本文将带你全面掌握：

✅ 小程序分包的基本原理
✅ 分包的配置方式（app.json）
✅ 主包与子包的通信机制
✅ 页面路径的引用规则
✅ 分包预下载策略
✅ 实战案例：如何将项目拆分为多个包
✅ 常见问题与解决方案

并通过完整的代码示例帮助你快速上手并灵活应用小程序分包技术。

二、什么是小程序分包？

小程序分包（Subpackages） 是一种将小程序代码拆分成多个独立包的技术。每个子包可以包含页面、组件、资源和部分 JS 模块。主包负责启动小程序并控制逻辑入口，子包则在需要时被动态加载。

✅ 分包的优势：

优势	描述
突破大小限制	单个子包最大 2MB，总包不超过 8MB
提升首屏加载速度	主包只包含核心页面，减少首次加载时间
按需加载	子包仅在访问相关页面时加载
易于维护更新	各模块独立开发、测试、部署

三、小程序分包的结构说明

project/
├── app.js
├── app.json
├── app.wxss
├── pages/                  <-- 主包页面
│   └── index/index.js
│   └── logs/logs.js
├── packageA/               <-- 子包 A
│   ├── pages/
│   │   └── list/list.js    <-- 可以访问 packageA 中资源
│   └── utils.js            <-- 子包内模块
├── packageB/               <-- 子包 B
│   ├── pages/
│   │   └── detail/detail.js
│   └── components/
│       └── custom-component.js
└── subpackages.json        <-- 可选：子包依赖配置文件（非必须）

四、配置小程序分包（app.json）

在 app.json 中通过 subpackages 字段定义分包结构。

{
  "pages": ["pages/index/index", "pages/logs/logs"],
  "subpackages": [
    {
      "root": "packageA",
      "pages": [
        {
          "path": "list/list",
          "style": "default"
        }
      ],
      "independent": true
    },
    {
      "root": "packageB",
      "pages": [
        {
          "path": "detail/detail",
          "style": "custom"
        }
      ]
    }
  ],
  "window": {
    "backgroundTextStyle": "light",
    "navigationBarTitleText": "小程序分包示例",
    "navigationStyle": "custom"
  }
}

✅ 配置说明：

属性	类型	说明
root	string	子包根目录路径
pages	array	子包中包含的页面列表
independent	boolean	是否为独立分包（默认 false）
style	string	页面样式风格（可选）

五、分包间通信与资源共享

✅ 1. 主包 → 子包：共享全局变量

// app.js
App({
  globalData: {
    theme: 'dark'
  }
});

// packageA/list/list.js
const app = getApp();
Page({
  onLoad() {
    console.log('当前主题：', app.globalData.theme);
  }
});

✅ 2. 子包调用主包模块

主包中的模块（如 utils.js）可以被子包引用：

// pages/utils.js
function formatTime(time) {
  return time.toLocaleString();
}
module.exports.formatTime = formatTime;

// packageA/list/list.js
const { formatTime } = require('../../pages/utils');
Page({
  onLoad() {
    console.log('格式化时间：', formatTime(new Date()));
  }
});

❌ 注意事项：

• 子包不能直接引用其他子包的文件。
• 子包之间不能相互导入或 require。

六、独立分包（Independent Subpackage）

设置 "independent": true 的子包称为 独立分包，它不依赖主包和其他子包，可以单独运行。

✅ 使用场景：

• 游戏类小程序（如“跳一跳”）
• 多入口小程序（如企业不同业务线）
• 超大模块（如地图、视频播放器）

⚠️ 限制：

• 不能使用主包中定义的全局变量（除非显式传参）
• 不能引入主包或其他子包的 JS 文件
• 不能使用主包注册的自定义组件

七、分包预下载策略优化性能

微信小程序支持在用户操作前预下载子包，提升用户体验。

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

✅ 配置说明：

属性	类型	说明
network	string	预加载网络类型，可选 wifi / all
packages	array	要预加载的子包名数组

八、实战案例：将项目拆分为多个子包

✅ 场景描述：

我们有一个本地生活类小程序，首页为主包，商品列表和详情页为两个子包。

✅ 步骤如下：

1. 创建子包目录

project/
├── packageList/     <-- 商品列表页
│   └── pages/
│       └── list/list.js
├── packageDetail/   <-- 商品详情页
│   └── pages/
│       └── detail/detail.js

2. 修改 app.json

{
  "pages": ["pages/index/index"],
  "subpackages": [
    {
      "root": "packageList",
      "pages": [
        {
          "path": "list/list",
          "style": "default"
        }
      ]
    },
    {
      "root": "packageDetail",
      "pages": [
        {
          "path": "detail/detail",
          "style": "custom"
        }
      ]
    }
  ],
  "preloadRule": {
    "pages/index/index": {
      "network": "all",
      "packages": ["packageList", "packageDetail"]
    }
  }
}

3. 页面跳转示例

// pages/index/index.js
Page({
  gotoList() {
    wx.navigateTo({ url: '/packageList/pages/list/list' });
  },
  gotoDetail() {
    wx.navigateTo({ url: '/packageDetail/pages/detail/detail' });
  }
});

九、常见问题与解决方案

问题	原因	解决方案
页面路径错误	路径未正确添加子包前缀	使用 /packageA/pages/xxx 形式
模块找不到	子包引用了其他子包模块	不允许跨包引用，应合并或移动
首次加载慢	未开启预加载	添加 preloadRule 预加载策略
包大小超限	单个子包超过 2MB	拆分更细粒度或优化资源
独立包无法访问全局变量	独立包不继承主包状态	手动传递参数或使用本地缓存

十、总结对比表：分包机制一览

特性	主包	子包	独立子包
最大体积	2MB	2MB	2MB
可否被其他包引用	✅	❌	❌
可否访问主包模块	✅	✅	❌
可否访问其他子包模块	✅	❌	❌
是否支持预加载	✅	✅	✅
是否能独立运行	❌	❌	✅

十一、结语

感谢您的阅读！如果你有任何疑问或想要分享的经验，请在评论区留言交流！