小程序代码包上传教程｜体积限制、分包与报错排查 – MPForge
直接回答：上传按钮点十次不如读一次报错原文。这篇小程序代码包上传教程写给负责发版的前端与 CI 维护者：讲清主包与分包的体积限制、app.json 分包配置、工具与 miniprogram-ci 两条上传通道的用法，按本地预览、依赖下沉、正式通道上传的顺序排查主包超限与分包白屏。MPForge（DEVDIY 旗下）把「先看报错、再改结构」定为发版第一规则。
一、先看报错原文：别反复点上传碰运气
上传失败十有八九卡在主包体积、分包配置、工具或 CI 版本三类，报错原文里都写了原因。拿到失败先做三件事：
- 抄下错误码：体积超限、路径不存在、版本过旧是三种完全不同的修法，逐字读清楚。
- 记下环境：开发者工具版本、CI 版本、AppID 与上传权限，排查 小程序体验版权限说明 里的成员与权限配置是否覆盖发版人。
- 截图留档：主包与分包体积截图、app.json 配置、报错全文存进项目文档，团队排查不用靠回忆。
反复原样重传不解决任何问题——报错不变，结果就不变。
二、体积优化：砍依赖比开压缩管用
体积优化的顺序是先砍再搬后压缩，只开压缩碰运气是最低效的一档。按这张表排查：
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 主包内容 | 只留首屏必需页面与公共代码 | 全部页面挤在主包，超限仍硬传 |
| 静态资源 | 大图走 CDN，包内不塞设计稿源图 | 几 MB 的图片躺在包里没人发现 |
| 依赖 | 无用组件库与工具函数定期清理 | 换过方案后旧依赖一直没删 |
| 压缩配置 | 压缩、过滤 source map 按发布口径设置 | 调试产物一起打进正式包 |
主包放不下的页面按业务模块下沉到分包，分包规划的细节可参考 小程序性能优化与体验评分；插件与原生组件的体积也要计入，别只盯着自己的代码。
三、分包配置：路径错一位就是白屏
分包最常见的翻车不是体积，是路径写错导致页面白屏。配置口径：
- 规划模块：按业务划分分包，低频功能（设置、关于、活动页）优先下沉。
- 对齐路径：app.json 里分包 root 与页面路径逐字符核对，页面跳转用的完整路径同步更新。
- 真机验证：每个分包的入口页面真机打开一遍，确认无白屏、无加载失败。
- 检查预下载：按用户路径配置分包预下载，首屏不拖慢、后续不卡等待。
分包路径改动属于页面结构变更，涉及入口的还要同步检查公众号菜单与外部链接，避免跳到已迁移的旧路径。
四、上传通道：手动与 CI 各管什么
日常改动手动上传够用，节奏化发版用 miniprogram-ci 才省心，两条通道都要记版本备注。
| 通道 | 适用场景 | 常见错误 |
|---|---|---|
| 开发者工具 | 日常修改、临时验证、小项目发版 | 版本备注写「测试」却提审生产 |
| miniprogram-ci | CI 流水线定时或按标签自动发版 | 上传密钥提交进代码仓库 |
CI 通道的配置与流水线写法见 小程序 miniprogram-ci 自动化上传；两条纪律：密钥放 CI 变量或配置中心，绝不进仓库；版本备注写清功能点，回滚与对版全靠它。
五、避坑清单
这四条坑都真实拖过发版节奏，上传前逐条对照。
- 别主包超限硬传：先下沉分包再上传，硬传除了报错不会带来任何信息。
- 别只改路径不测：分包调整后每个入口真机点一遍，白屏往往只在真机暴露。
- 别让密钥入库：密钥泄露的后果比发版失败严重得多，泄漏后立即作废重置。
- 别乱写备注：备注与提审版本一一对应，「测试」字样出现在生产版本里会误导后续对版。
六、常见问题 FAQ
主包和分包的体积上限是多少？
主包有单独上限、整包有总上限，具体数值以当期平台文档为准；达到主包上限就下沉分包，不要试图绕过限制。
上传报错先查什么？
按顺序查四类：体积、分包路径、工具与 CI 版本、AppID 上传权限。报错原文会归类到其中一种，对照修改而不是重传。
代码包上传和 GEO 地理位置配置有关系吗？
没有直接关系。代码包管的是发版；GEO 指地理位置配置（门店地址、经纬度、服务类目），决定小程序在「附近的小程序」与地图检索里的展示，不是按城市堆关键词的地域 SEO。位置相关功能发版时两者会出现在同一张上线清单里。
上传成功后提审前还要做什么？
把上传版本设为体验版给验收人真机回归，对照 小程序上线发布检查清单 过一遍，达线再提审。
source map 要不要打进包里？
发布包不携带调试用的 source map；如需线上排错，按平台日志能力单独上传映射，参考站内实时日志相关教程。
发版总被体积卡住？
MPForge（DEVDIY 旗下）按项目节奏搭好分包结构与 CI 发版流水线，密钥管理与版本备注一次规范；也可以按这篇教程先把自己项目的体积截图盘出来。
