uni-app开发微信小程序分包

uni-app 分包开发

一、什么是分包

分包是指将小程序的代码和资源按照功能模块划分为多个包，主包和分包可以独立加载。微信小程序有严格的限制：所有分包和主包的大小总和不能超过 20MB，单个分包/主包不能超过 2MB。

二、为什么需要分包

包体积限制：当项目体积过大时，必须使用分包来规避 2MB 的限制
优化加载速度：按需加载分包，减少首屏加载时间
模块化管理：不同功能模块独立开发和维护

三、分包目录结构

src/
├── pages/              # 主包页面
│   └── index/
├── pages-manage/       # 分包目录
│   ├── facility/       # 分包页面
│   │   └── index.vue
│   ├── components/     # 分包专用组件
│   │   ├── TreeSelector.vue
│   │   ├── TreeNode.vue
│   │   └── TreeNodeItem.vue
│   └── api/           # 分包专用 API
│       └── facility/
│           └── index.ts

四、配置分包

vite.config.ts 配置分包

      UniPages({
        exclude: ['**/components/**/**.*'],
        // pages 目录为 src/pages，分包目录不能配置在pages目录下！！
        // 是个数组，可以配置多个，但是不能为pages里面的目录！！
        subPackages: [
          'src/pages-core', // 这个是相对必要的路由，尽量留着（登录页、注册页、404页等）
          'src/pages-system', // "系统管理"模块
          'src/pages-infra', // "基础设施"模块
          'src/pages-bpm', // "工作流程"模块
          'src/pages-manage', // "管理"模块 新增模块在这里
        ],
        dts: 'src/types/uni-pages.d.ts',
      }),

manifest.config.ts 配置（可选优化）

export default defineManifest({
  // 微信小程序配置
  mp-weixin: {
    componentIsolation: true,      // 组件隔离
    ignoreUploadUnusedFiles: false, // 不忽略未使用的文件
  },
})

五、分包开发的注意事项

1. ⚠️ 跨包引用限制
   主包不能引用分包中的文件

<!-- ❌ 错误：主包页面引用分包组件 -->
<template>
  <TreeSelector />  <!-- TreeSelector 在分包中 -->
</template>

分包不能引用主包中的模块

// ❌ 错误：分包 API 引用主包工具
import { formatDate } from '@/utils'

// ❌ 错误：分包页面引用主包组件
import TreeSelector from '@/components/TreeSelector'

2. ✅ 正确的引用方式
   分包内部使用相对路径引用

// ✅ 正确：分包 API 内部引用分包工具
import { getTreeNoCache } from '../api/facility'

// ✅ 正确：分包页面引用分包组件
import TreeSelector from '../components/TreeSelector.vue'

// ✅ 正确：分包页面引用分包 API
import { getDeviceByCode } from '../api/facility'

六、最佳实践

按功能划分分包：相关的页面、组件、API 放在同一个分包内
减少跨包依赖：每个分包尽量自包含，避免依赖其他包
使用相对路径：分包内部统一使用相对路径引用
区分导入类型：组件导入不要使用 import type
及时删除无用文件：避免分包体积过大

七、总结

分包开发的关键是理解包的边界：
✅ 同一个包内可以自由引用
❌ 不同包之间不能相互引用
✅ 使用相对路径访问同包资源
❌ 避免跨包依赖