UniApp 分包处理详细指南

一、分包原理

UniApp 分包是将小程序拆分为多个独立模块的技术：

• 主包（必含）：启动页面、公共资源
• 分包：按需加载的功能模块
• 优势：
  • 首次启动只加载主包（≤2MB）
  • 总包上限提升至 20MB（微信小程序）
  • 优化用户体验

---

二、配置步骤

1. 项目结构规划

project-root/
├── pages/               # 主包页面
├── static/              # 主包资源
├── subpackageA/         # 分包A
│   ├── pages/           # 分包页面
│   └── static/          # 分包资源
└── subpackageB/         # 分包B

2. 修改 pages.json

{
  "pages": [
    // 主包页面配置
    {"path": "pages/index/index", "style": {...}}
  ],
  "subPackages": [
    {
      "root": "subpackageA",   // 分包根目录
      "pages": [               // 分包页面路径（相对root）
        {"path": "goods/list", "style": {...}},
        {"path": "goods/detail", "style": {...}}
      ]
    },
    {
      "root": "subpackageB",
      "pages": [
        {"path": "user/profile", "style": {...}}
      ]
    }
  ],
  "preloadRule": {         // 预加载配置（可选）
    "pages/index/index": {
      "network": "all",
      "packages": ["subpackageA"]  // 进入首页时预加载分包A
    }
  }
}

3. 分包跳转示例

// 跳转到分包页面
uni.navigateTo({
  url: '/subpackageA/goods/list'  // 绝对路径（从项目根目录开始）
})

// 返回主包页面
uni.navigateBack()

---

三、关键代码实现

1. 分包独立组件（subpackageA/components/GoodsCard.vue）

<template>
  <view class="goods-card">
    <image :src="localImage"></image>
    <text>{{ title }}</text>
  </view>
</template>

<script>
export default {
  props: ['title'],
  data() {
    return {
      // 分包内图片使用相对路径
      localImage: './static/goods-icon.png'
    }
  }
}
</script>

2. 分包异步加载（使用 require）

// subpackageB/user/profile.vue
export default {
  mounted() {
    // 动态加载分包模块
    const utils = require('../../common/utils.js')
    utils.showToast('加载完成')
  }
}

---

四、注意事项

1. 资源引用规则：

   • 分包内图片/字体：使用相对路径 ./static/xx.png
   • 禁止主包引用分包资源（否则会被打包进主包）

2. 跳转限制：

   // 错误！不能直接跳转到分包内非页面目录
   uni.navigateTo({ url: '/subpackageA/components/GoodsCard' })
   

3. 大小限制：

   • 主包 ≤ 2MB
   • 单个分包 ≤ 2MB
   • 总包 ≤ 20MB

4. 优化建议：

   • 公共组件放在主包 components 目录
   • 使用 preloadRule 预加载高频分包
   • 通过 uni.getSubpackageInfo() 监控分包状态

---

五、验证分包

1. 构建命令：

   npm run build:mp-weixin
   

2. 查看微信开发者工具：
   • 编译日志显示分包大小
   • 通过「代码依赖分析」检查资源分布

分包处理可显著提升小程序启动速度，建议将低频功能（如设置页、帮助中心）放入分包。