小程序版本管理，别让线上事故重演

小程序上线后，最怕的不是功能少，而是版本乱。用户反馈的问题在线上复现不了，开发本地却一切正常；紧急修复提交审核，结果把别人没测完的代码一起带了上去。这类问题根源往往不在代码质量，而在版本管理没有形成约束。本文从分支模型、构建产物、灰度与回滚三个层面，讲一套能落地的小程序版本管理方式。

一、先定分支模型，再谈发布

小程序项目通常由一到三人维护，不需要复杂的 Git Flow，但必须有一条明确的“可发布线”。推荐使用简化版主干开发：

• main：始终对应线上稳定版本，任何提交都必须能直接提审。
• feature/*：功能开发分支，从 main 切出，完成后合并回 main。
• hotfix/*：线上紧急修复分支，从 main 切出，修复后同时合回 main。

关键约束只有一条：feature 分支不直接提审。提审动作永远发生在 main 上，这样线上版本与仓库提交一一对应，出问题时能立刻定位到是哪次合并引入的。

用 tag 标记每一次提审

每次提交审核前打一个 tag，格式建议为 v主版本.次版本.修订号，并在 tag 说明里写清提审时间和审核单号。微信开发者工具上传代码时会生成版本号，但那个版本号只存在于平台侧，和仓库没有绑定关系。tag 是两边对齐的唯一凭据。

git checkout main
git pull origin main
git tag -a v1.4.2 -m "提审 2024-06-12 审核单 123456"
git push origin v1.4.2

二、构建产物与配置分离

小程序没有传统意义上的构建服务器，但 project.config.json 和接口域名这类配置最容易在多人协作中互相覆盖。做法是把环境相关配置抽成独立文件，按环境注入：

• config/dev.js、config/staging.js、config/prod.js 各自维护接口地址、AppID、是否开启调试日志。
• 入口文件根据构建变量选择配置，构建变量不进入版本库。
• project.config.json 中的 appid 字段保持为占位或统一值，避免个人调试时误提交。

这样切换体验版和正式版时，不需要手工改代码，也杜绝了“测试环境域名被带到线上”的低级事故。

三、灰度发布与版本回滚

微信平台提供了分阶段发布能力，但很多团队提审通过后直接全量。建议把发布拆成三步：

1. 体验版验证：提审前用体验版走一遍核心链路，体验版二维码对应固定 tag。
2. 分阶段发布：审核通过后先按 10% 比例放量，观察一到两天内的错误日志和关键转化指标。
3. 全量：指标平稳后再放开剩余比例。

回滚同样要提前设计。小程序支持在后台将线上版本回退到上一个已发布版本，但前提是上一个版本仍然可用。因此服务端接口必须保持向后兼容至少两个版本：新增字段可以，删除或改语义不行。否则回滚了前端，接口却已经不认旧参数，等于没回滚。

判断一个团队版本管理是否成熟，看的不是发布多快，而是出问题时能不能在十分钟内回到已知可用的状态。

四、把版本记录写进日常流程

再好的规范，不落到检查项里都会退化。可以在仓库根目录维护一个 CHANGELOG.md，每次合并到 main 时补一行：版本号、变更内容、影响范围、是否涉及接口改动。配合 tag 使用，任何时候都能回答三个问题——线上跑的是哪份代码、它改了什么、上一个稳定版本是什么。

对于个人开发者，这套流程的全部成本大约是一次性半小时搭好分支和配置文件，之后每次发布多花两分钟打 tag、写一行日志。换来的，是线上出问题时不必靠记忆去猜哪次提交动了什么。版本管理的价值，恰恰体现在那些没有发生的事故里。