【开发】开源项目二开 + 持续同步上游更新：标准Git分支管理方案

一、核心分支架构（固定规范，兼顾自定义开发+上游同步）

分支规划

1. upstream/main（远程上游，只读，官方开源主分支）
2. origin/main（你的仓库镜像，完全同步上游，不写任何二开代码）
3. origin/dev（二开开发分支：所有自定义功能、改逻辑、前端、业务定制全部在这里写）
4. origin/release（生产部署分支：dev稳定后合并到此，线上跑）

核心原则

• 永远不在同步上游的纯净分支写自定义代码，所有二开修改隔离在独立分支；
• 上游更新只合并到纯净main，再rebase/merge到你的开发分支，不会冲突覆盖你的二开逻辑。

二、第一步：初始化仓库（仅第一次操作）

1. Fork 官方开源仓库到自己Gitee/GitHub

2. 本地克隆你的仓库，并绑定上游源

# 克隆你fork后的仓库
git clone git@github.com:你的账号/xxx.git
cd xxx

# 绑定官方上游仓库（命名upstream）
git remote add upstream git@github.com:原始作者/xxx.git

# 验证远程
git remote -v
# 会出现 origin（你的仓库）、upstream（官方原仓库）

3. 建立分支基础

# 本地main同步官方纯净代码，不动二开
git checkout main
git pull upstream main

# 创建二开开发分支dev
git checkout -b dev

三、日常开发流程（你的二开业务代码全部在dev）

1. 切到dev分支做定制开发：改前端、加参数覆盖、日志隐藏、新增接口等
2. 频繁commit、push到自己仓库origin/dev
3. 禁止在main分支提交任何自定义代码，main只用来同步官方更新

四、关键：同步上游新版本（拉官方更新并合并进二开分支，无代码覆盖）

方式A：rebase 推荐（提交记录干净，适合持续迭代）

适合：你希望提交历史线性、方便排查冲突

# 1. 先同步官方最新代码到本地纯净main
git checkout main
git fetch upstream
git pull upstream main
git push origin main # 同步纯净上游到你仓库main备份

# 2. 切回你的二开分支dev，基于最新上游重构你的二开代码
git checkout dev
git rebase main

rebase冲突处理：

1. 弹出冲突文件，手动修改代码，保留你的二开逻辑 + 官方新代码
2. 单个冲突修复后执行 git add .
3. 全部冲突处理完 git rebase --continue
4. 中途想放弃同步：git rebase --abort

优势：官方新增功能完整合并，你的定制修改自动叠加在新版本之上；

缺点：多人协作时rebase会改写历史，单人二开完全无压力。

方式B：merge 简单稳妥（多人协作首选，历史不破坏）

不想改写提交记录、团队多人开发用merge

# 1. 同步上游到main
git checkout main
git fetch upstream
git pull upstream main
git push origin main

# 2. 把最新官方main合并进二开dev
git checkout dev
git merge main

冲突解决完直接commit，生成一条「同步上游」合并记录，历史永久保留，回滚更简单。

五、生产发布流程

dev分支测试稳定后，合并到release部署分支

git checkout release
git merge dev
git push origin release
# 服务器拉取release分支部署

六、必须规避的致命坑（90%二开踩雷）

1. ❌ 直接在main分支写二开代码
   后果：同步上游时大量冲突，分不清哪些是你的修改、哪些是官方代码，无法持续更新
2. ❌ 同步上游时直接覆盖代码，不处理冲突
   后果：你的自定义逻辑被官方新版本冲掉，之前开发全部丢失
3. ❌ fork后不绑定upstream远程，只会拉自己仓库代码
   后果：永远拿不到官方新功能、bug修复
4. ❌ 直接在rebase中途强制推送覆盖远程dev
   单人使用没问题，多人协作会导致同事代码丢失

七、补充实用配套方案

1. 补丁文件备选（轻量二开，改动极少）

如果你的修改只有几处少量代码，不想维护长期分支：

• 开发完成后导出补丁 git diff > custom.patch
• 每次拉完上游新版本，执行 git apply custom.patch 自动打自定义补丁
  适合：仅改前端文字、少量配置、隐藏字段这种小幅修改

2. 子模块拆分（重度二开推荐）

如果自定义功能非常多：日志权限、新增路由逻辑，把自己的业务代码拆成独立git子模块，主仓库保持纯净上游，子模块存放所有二开逻辑，同步上游完全无冲突。

3. 提交规范（方便长期合并）

二开提交注释统一加标记区分，冲突时快速定位：

[custom] 新增参数兼容
[upstream sync] 合并官方v1.5.0新版本

极简流程总结

1. 本地main = 纯净官方代码，定期git pull upstream main同步更新
2. dev = 你的所有二开代码，基于main创建
3. 要更新官方功能：main同步上游 → dev rebase/merge main，解决冲突
4. 测试完成合并到release分支上线