LikeShop 单商户高级版二开项目的 Git 分支管理与版本发布规范

做电商系统二开的团队，大多都踩过分支管理的坑。

拿到 LikeShop 单商户高级版源码后，很多团队直接在主分支上改代码，功能上线时很快，但后续问题会集中爆发：官方发布新版本修复漏洞，不知道怎么合进来，一合就全量冲突；线上出了 bug，想回滚却找不到对应版本；多人并行开发，代码互相覆盖，上线前合并到凌晨。

本质问题在于：二开项目和纯自研项目不一样，它多了一个「上游官方基线」。普通的 GitFlow 只解决了自有业务的迭代，没有处理「官方版本同步 + 自有二开 + 生产发布」三者的关系。

基于 LikeShop 单商户高级版的二开场景，我们整理了一套可落地的分支管理与发布规范，核心思路是：官方基线隔离、二开分层迭代、发布可追溯、回滚有预案。

一、二开项目的特殊性与设计原则

普通自研项目只有一套代码，分支围绕「开发-测试-发布」展开。而 LikeShop 二开项目有两个代码源：

1. 官方基线代码：LikeShop 官方发布的标准版本，定期更新漏洞修复、性能优化、新功能；
2. 自有二开代码：基于官方版本做的业务定制、行业功能、对接第三方系统。

如果混在一起写，短期快，长期会付出几倍的维护成本。因此分支设计遵循三个原则：

• 物理隔离原则：官方原版代码和二开代码分层存放，互不污染；
• 最小侵入原则：二开尽量通过扩展、钩子实现，少改官方核心文件，降低同步成本；
• 可追溯原则：每个生产版本都对应唯一标签，可随时回滚到对应官方基线 + 二开版本。

二、分支模型与职责定义

在经典 GitFlow 基础上，新增「官方基线分支」，形成 6 类分支的分层结构。

2.1 分支总览

2.2 核心分支详解

1）官方基线分支：official/base

这是二开项目最容易缺失、也最重要的一条分支。

• 作用：纯净存放 LikeShop 官方发布的原版代码，不做任何二开修改，作为版本同步的基准。
• 更新规则：每次官方发布新版本，将官方源码完整更新到该分支，并打上对应官方版本标签，如 official/v4.2.0。
• 禁止操作：绝不允许在该分支直接写二开代码，否则基线就失去了意义。

2）主分支：main

• 对应生产环境运行的代码，永远保持可发布状态；
• 不允许直接提交代码，所有变更必须通过 release 或 hotfix 分支合并进入；
• 每次合并后必须打正式版本标签，如 v4.2.0.1-release。

3）开发主分支：develop

• 日常开发的集成分支，对应测试环境；
• 所有功能分支从这里切出，开发完成后合并回来；
• 官方新版本同步后，也先合并到 develop 分支验证，再进入发布流程。

4）功能分支：feature/xxx

• 每个独立需求/功能开一条分支，从 develop 切出，开发完成后合并回 develop；
• 命名规范：feature/功能模块简称，例如 feature/point-mall、feature/third-login；
• 功能开发完成并自测通过后，发起 Merge Request，代码评审通过后合并入 develop。

5）发布分支：release/x.y.z

• 当 develop 分支功能累积到可发布程度，从 develop 切出发布分支；
• 该分支只做 bug 修复、版本号更新、发布前检查，不新增功能；
• 测试通过后，同时合并入 main 和 develop，并在 main 上打版本标签。

6）热修复分支：hotfix/xxx

• 生产环境出现紧急 bug，从 main 分支直接切出修复；
• 命名规范：hotfix/问题描述，例如 hotfix/pay-callback-error；
• 修复完成后，同时合并回 main 和 develop，避免下次发布 bug 复现。

三、版本号命名规则

二开项目的版本号必须能直观体现「基于哪个官方版本、做了几轮迭代」，避免版本混乱。

3.1 版本号格式

采用 「官方主版本号.二开迭代号.补丁号」 四级结构：

官方大版本.官方小版本.二开迭代号.补丁号
例如：4.2.1.3

• 前三位 4.2.1 对应 LikeShop 官方基线版本；
• 第四位 3 表示基于该官方版本的第 3 次二开补丁/小版本；
• 二开大版本迭代时，升第三位，例如 4.2.2.0 表示二开做了较大功能升级。

3.2 标签命名规范

• 官方基线标签：official/v4.2.1
• 正式发布标签：v4.2.1.0-release
• 热修复标签：v4.2.1.1-hotfix
• 测试版本标签：v4.2.1.0-beta

标签必须打在 main 分支对应提交上，确保线上版本可一键定位、一键回滚。

四、核心场景工作流

4.1 日常功能开发流程

1. 从 develop 切出功能分支
   git checkout develop
   git checkout -b feature/point-mall

2. 功能开发与自测，提交代码
   git add .
   git commit -m "feat: 新增积分商城模块"

3. 合并回 develop，发起代码评审
   git checkout develop
   git merge --no-ff feature/point-mall
   git push origin develop

建议开启 --no-ff 合并，保留功能分支的提交轨迹，方便后续排查问题。

4.2 官方版本同步流程

这是二开项目最核心的操作，步骤错了很容易产生大量冲突。

1. 准备官方新版源码，更新到基线分支
   git checkout official/base
   # 全量替换为官方新版代码，保留 .git 目录
   # 提交并打官方标签
   git add .
   git commit -m "official: 升级到 v4.2.1"
   git tag official/v4.2.1

2. 合并到开发分支，处理冲突
   git checkout develop
   git merge --no-ff official/base

3. 重点解决冲突
   - 官方新增文件：直接保留
   - 自己新增的二开文件：直接保留
   - 双方都修改过的文件：对比官方变更，调整二开代码适配新版

4. 全量回归测试，确认核心链路正常
   重点验证：登录、下单、支付、退款、二开核心功能

5. 测试通过后，进入正常发布流程

关键提醒：每次同步官方版本前，务必备份当前 develop 分支，出现大面积冲突时可快速回退。

4.3 版本发布流程

1. 从 develop 切出发布分支
   git checkout develop
   git checkout -b release/4.2.1.0

2. 发布前准备
   - 更新版本号、配置文件
   - 执行发布前检查（依赖、SQL脚本、静态资源）
   - 测试环境回归测试，修复小 bug

3. 测试通过后合并入主分支和开发分支
   git checkout main
   git merge --no-ff release/4.2.1.0
   git tag v4.2.1.0-release

   git checkout develop
   git merge --no-ff release/4.2.1.0

4. 删除发布分支，推送代码与标签
   git branch -d release/4.2.1.0
   git push origin main develop
   git push origin --tags

4.4 线上紧急修复流程

1. 从主分支切出热修复分支
   git checkout main
   git checkout -b hotfix/pay-notify-error

2. 修复问题，自测通过
   git commit -m "fix: 修复支付回调重复通知问题"

3. 合并回主分支，打补丁标签
   git checkout main
   git merge --no-ff hotfix/pay-notify-error
   git tag v4.2.1.1-hotfix

4. 同步合并回 develop，避免下次发布丢修复
   git checkout develop
   git merge --no-ff hotfix/pay-notify-error

5. 删除热修复分支，推送上线
   git branch -d hotfix/pay-notify-error

红线：hotfix 绝对不能只更 main 不更 develop，否则下一次发布时 bug 会重新出现。

五、配套规范：SQL 脚本与配置管理

二开项目里，数据库变更和环境配置也是混乱重灾区，必须和代码分支一起管理。

5.1 SQL 脚本管理

• 仓库内建 sql/ 目录，分两类子目录：
  • sql/official/：存放官方版本升级脚本，按官方版本号命名；
  • sql/extra/：存放二开新增的表、字段、数据脚本，按二开版本号命名。
• 每次版本发布，对应 SQL 脚本随代码一起提交，发布时按顺序执行。

5.2 环境配置隔离

• 配置文件按环境拆分：dev、test、prod，分别对应开发、测试、生产；
• 敏感信息（数据库密码、支付密钥）不入库，通过环境变量或配置中心注入；
• 不同分支对应不同环境配置，避免发布时把测试配置带到生产。

六、常见坑与避坑建议

1. 没有官方基线分支，直接在主分支改官方代码

后果：每次官方更新都要手动对比文件，冲突多到没法合，最后变成「一次性版本」，永远停在旧版。
避坑：项目初始化第一天就建立 official/base，纯净存放官方代码。

2. 功能分支长期不合并，越拖冲突越多

后果：一个功能开发半个月，合并时发现大量文件冲突，排期直接延期。
避坑：小功能快速开发、快速合并；大功能拆分子任务，分批合入 develop。

3. hotfix 只更 main 不更 develop

后果：线上 bug 修好了，下一次发布时 develop 里的旧代码又把 bug 带上线。
避坑：所有 hotfix 必须同时合并回 main 和 develop，作为发布流程的强制检查项。

4. 版本号随意打，线上版本对不上

后果：线上出了问题，不知道对应哪次提交，回滚找不到准确节点。
避坑：每次发布必须打标签，标签和版本号一一对应，发布记录里写明基于哪个官方版本。

5. 大文件、依赖包入库

后果：仓库体积越来越大，克隆、拉取越来越慢。
避坑：vendor、node_modules、编译产物、大图片一律加入 .gitignore，通过依赖管理工具安装。

七、结语

Git 分支管理从来不是炫技，是为了降低协作成本、降低线上风险。

对于 LikeShop 二开项目来说，这套规范的核心价值体现在三个地方：

• 官方版本可平滑同步：基线隔离，合入成本可控，能跟着官方持续获得安全修复和新功能；
• 线上故障可快速回滚：每个版本有唯一标签，出问题能一键切回稳定版本；
• 多人协作可有序推进：功能分支、发布分支、热修复分支各司其职，不会互相覆盖。

前期花一点时间把分支规范搭起来，后续每次版本迭代、每次官方升级，都能省下几倍的排障和合并时间。