小程序 CI 上传与预览教程｜密钥、机器人与流水线避坑 – MPForge
直接回答：小程序 CI 上传能把「开工具、点上传、手写备注」这套手工活交给流水线，但前提是管住三样东西：上传密钥、机器人权限、版本备注规范——密钥明文进代码仓库是高危事故，生产提审必须保留人工确认闸门。这份教程面向开发与项目负责人，给出材料清单、五步流水线搭建法与高频翻车点。MPForge（DEVDIY 旗下）交付的小程序项目默认带这套 CI 配置，构建上传一条命令完成。
一、CI 上传解决什么，又不能做什么
结论是：CI 负责把版本「送到」微信后台，生产发布这一步永远留给人。
没有 CI 的团队每天都在重复：打开开发者工具、点预览、截图二维码发群、再点上传手写备注。一天三遍，版本号全靠记忆。CI 把这些变成流水线任务后，收益立刻可见——备注自动带上分支与提交号，体验版二维码自动推到固定群，谁改了什么一查便知。
但要划清边界：CI 擅长重复执行，不擅长做判断。提审生产版本涉及「这次改动该不该上」的业务判断，这一步必须有人点确认。见过最严重的翻车，就是流水线被配成「合并即自动提审生产」，一次误合并直接把未验收的改动送到了审核队列。
二、四份材料：密钥、机器人、节点、版本号规范
流水线跑不起来，九成卡在材料没备齐。开工前逐项确认：
| 材料 | 要怎么准备 | 缺了或错了会怎样 |
|---|---|---|
| 代码上传密钥 | 公众平台生成后放密钥管理系统，加密存储、定期轮换 | 明文进仓库等于把发布权交给所有能读库的人 |
| 机器人账号 | 专用机器人身份，按需分配权限，不挂个人微信号 | 共用个人账号，人一离职权限就失控 |
| 流水线节点 | 构建机装好 CLI，IP 白名单加上流水线出口地址 | 上传被拒，报错查半天才发现是 IP 没放行 |
| 版本号规范 | 约定分支、版本号与备注格式，如分支加日期加序号 | 版本满天飞，回滚时不知道退到哪 |
上传后的包体积控制与分包策略，见 代码包上传与分包体积优化，CI 里可以顺手加体积阈值检查，超限直接红。
三、五步搭好上传与预览流水线
按这个顺序搭，每步都有明确的验收标准：
- 生成并妥善存储密钥：在公众平台生成代码上传密钥，录入密钥管理系统，流水线运行时注入环境变量，仓库里永远不出现密钥明文；
- 流水线安装 CLI 并配置权限：构建节点装好 miniprogram-ci，出口 IP 加进后台白名单，用机器人账号做上传身份；
- 构建后带备注上传：备注自动拼上分支名、提交号与构建时间，版本号按规范递增，禁止「测试」这类空备注；
- 体验版二维码自动进群：上传成功后机器人把预览二维码推到固定的开发群，测试扫码即验，不用等人转发；
- 失败告警到负责人：上传失败、体积超限、白名单被拒都触发告警，直接通知当次提交人，不等第二天才发现版本没上去。
体验成员的范围管理同样要严：体验成员权限设置 里控制谁能拿到体验版，离职人员的访问权要及时移除。
四、预览与上传的分工口径
一句话分清：预览是临时验证，上传才生成正式版本。日常按这张表执行：
| 动作 | 适用场景 | 常见错误 |
|---|---|---|
| 预览 | 开发自测、双人结对的临时验证，码有时效 | 拿预览码当体验版给客户演示，过期尴尬 |
| 上传 | 生成后台版本记录，供提审或设为体验版 | 备注空白，版本记录里谁也分不清哪是哪 |
| 多人并发 | 约定分支与版本号区间，各占各的段位 | 互相覆盖版本，后传的顶掉先传的 |
| 生产提审 | CI 备好版本，人工确认后再提审 | CI 直提生产，未验收改动进了审核 |
五、避坑清单
四类事故在 CI 化项目里反复出现，配流水线时逐条设防：
- 密钥明文进 Git：哪怕私有仓库也算泄露，一旦提交过就要按已泄露处理——立即在后台作废重生成，不要抱侥幸心理；
- 共用个人账号传版本：人走权限乱，机器人账号加密管存储是唯一可持续的方案；
- 版本无备注满天飞：备注进不了版本记录，回滚就成了猜谜，规范要在第一天就定死；
- CI 直提生产未经确认：流水线终点设在「版本已备好」，提审按钮永远留在人手里。
六、常见问题 FAQ
必须用官方的 miniprogram-ci 吗？
它是最常见的选择，与微信后台的兼容性最好；团队如果已有成熟的构建栈，也可以在流水线里组合封装，关键是密钥管理与版本规范这两层自己守住。
多人同时上传会互相覆盖吗？
会。同一个 AppID 的版本记录是共享的，后上传的会排在前面。约定分支与版本号规则、错峰上传，或者在流水线里加占用锁，都能避免踩踏。
预览和上传到底差在哪？
预览偏临时验证，二维码有时效、不留版本记录，适合自测和结对面验；上传生成正式的版本记录，可以设为体验版或提审，对外交付一律以版本为准。
这个和 GEO 地理位置配置有关系吗？
没有关系。GEO 指小程序的地理位置配置——门店地址、经纬度、服务类目，影响「附近」检索展示，不是按城市做地域 SEO；CI 管的是代码怎么进后台，两者各管一段。
密钥多久轮换一次？
建议按季度轮换，人员变动、疑似泄露、流水线迁移时立即换。轮换当天同步更新密管里的版本，旧密钥作废前先跑一遍上传验证新链路通畅。
想让小程序构建上传全自动跑起来？
MPForge（DEVDIY 旗下）按你的代码仓库与团队规模搭好 CI 上传流水线，密钥入密管、二维码进群、失败告警到人，商家只管验收版本。
