微信小程序分包优化指南

问题背景

微信小程序主包有 2MB 的体积限制，当项目体积超出限制时会导致发布失败。通过合理的分包策略，可以将组件、页面、资源等按功能模块拆分到不同的子包中，有效解决体积限制问题。

分包策略

🎯 分包原则

1. 主包最小化：只保留核心页面和必要组件
2. 按功能分组：相关功能的组件和页面放在同一分包
3. 延迟加载：分包内容在需要时才加载，提升首屏性能
4. 资源共享：公共组件可以被多个分包引用

📊 分包限制

• 主包限制：2MB
• 单个分包限制：2MB
• 总包体积限制：20MB
• 分包数量限制：最多 20 个

配置步骤

步骤 1：启用分包功能

在 manifest.json 文件中的小程序配置下添加分包优化选项：

{
  "mp-weixin": {
    "appid": "your_appid_here",
    "optimization": {
      "subPackages": true // 启用分包代码优化
    }
  }
}

配置说明：

• subPackages: true：启用 uni-app 的分包代码优化
• 自动处理分包间的依赖关系和代码分割

步骤 2：配置分包页面和组件

在 pages.json 中定义分包结构：

{
  "pages": [
    {
      "path": "pages/index",
      "style": {
        "navigationBarTitleText": "首页",
        "usingComponents": {
          "a-com": "/src/sub-common/components/a-com.vue",
        },
        "componentPlaceholder": {
          "a-com": "view"
        }
      }
    }
  ],
  "subPackages": [
    {
      "root": "sub-common",
      "name": "common",
      "pages": [
        { // 建一个vue文件就可以,主要用到components
          "path": "index",
          "style": {
            "navigationBarTitleText": "公共组件包"
          }
        }
      ]
    },
  ]
}

配置说明：

• root：分包的根目录
• name：分包别名（可选，便于调试）
• usingComponents：声明页面使用的组件
• componentPlaceholder：组件加载时的占位标签

步骤 3：在页面中使用分包组件

主包页面使用分包组件

<!-- pages/index.vue -->
<template>
  <view class="container">
    <!-- 分包组件会自动按需加载 -->
    <aCom />
  </view>
</template>

<script setup lang="ts">
import { ref } from "vue";
import aCom from "@/sub-common/components/a-com.vue";
</script>

最佳实践

✅ 推荐做法

1. 公共组件分包：

sub-common/
├── components/
│   ├── a-com.vue      # 分包组件
└── index.vue                    # 占位页面

预加载策略：

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

❌ 避免的问题

1. 循环依赖：避免分包之间相互引用
2. 过度分包：不要为了分包而分包，保持合理的分包数量
3. 资源重复：避免在多个分包中重复引入相同的资源
4. 分包过小：避免创建体积过小的分包，影响加载效率

常见问题解决

Q1: 组件找不到

问题：分包组件无法正常加载
解决：确保在 pages.json 中正确声明了 usingComponents

Q2: 分包加载失败

问题：分包页面访问时报错
解决：检查分包路径配置是否正确，文件是否存在

Q3: 体积仍然超限

问题：分包后主包体积仍然超过 2MB
解决：

• 检查是否有大文件未移到分包
• 优化图片资源，使用 webp 格式
• 移除未使用的依赖和代码

Q4: 分包组件样式异常

问题：分包中的组件样式不生效
解决：确保样式文件正确引入，检查 CSS 作用域https://blog.csdn.net/qp66797/article/details/149097370