小程序分包

当微信小程序主包接近 2MB 限制时，将低频或依赖较重的页面拆到分包中。项目已在 vite.config.ts 预留分包目录 src/subPages，但当前还没有分包页面，后续按本文操作即可。

什么时候分包

放主包 src/pages	放分包 src/subPages
TabBar 页面、登录页、首屏必须秒开的页面	详情页、编辑页、配置页等低频页面
	图表、富文本、文件预览等依赖较重页面

原则：主包只保留启动就可能访问的页面。

目录结构

按业务域组织，避免所有低频页面堆在同一层：

src/subPages/
├── system/
│   └── user/detail.vue
├── report/
│   └── visit-trend.vue
└── settings/
    └── advanced.vue

生成后的路径：

/subPages/system/user/detail
/subPages/report/visit-trend

新增分包页面

在 src/subPages/ 下创建页面文件，用 definePage() 声明配置，与主包页面写法一致：

<script setup lang="ts">
definePage({
  name: "userDetail",
  style: {
    navigationBarTitleText: "用户详情",
  },
  meta: {
    requireAuth: true,
  },
})
</script>

跳转：

// uni-mini-router
router.push({ path: "/subPages/system/user/detail", query: { id } })

// 原生
uni.navigateTo({ url: `/subPages/system/user/detail?id=${id}` })

页面布局、权限守卫、路由配置与主包页面完全一致，参见：

• 路由系统 — definePage()、meta.requireAuth、页面跳转
• 布局系统 — layout 字段、layout: false
• 项目部署 — 分包构建检查、体积优化

分包内组件

只服务某个分包的组件放在分包内部即可：

src/subPages/report/
├── components/
│   └── TrendCard.vue
└── visit-trend.vue

vite.config.ts 已配置 exclude: ["**/components/**/*.*"]，分包内的 components 目录不会被误识别为页面。多分包复用的组件放 src/components/。

构建检查

pnpm run build:mp-weixin

确认 dist/build/mp-weixin/app.json 中存在 subPackages 字段，并在微信开发者工具中检查主包/分包体积。