开源项目二开 Git 规范工作流

以开源项目 RuoYi 为例。

RuoYi 二开 Git 规范文档

适用项目：基于 RuoYi-Vue3(master 分支)的二次开发

目标：可长期维护、可同步上游、可团队协作、可稳定发布

一、分支模型总览

分支	用途	含业务逻辑	是否可直接上线	来源
`main`	✅ 生产发布分支	✅ 是	✅ 是	`upstream/master` + 稳定业务代码
`dev`	✅ 集成开发分支	✅ 是	❌ 否	从 `main` 切出
`feature/xxx`	单功能开发	✅ 是	❌ 否	从 `dev` 切出
`hotfix/xxx`	紧急修复	✅ 是	✅ 是	从 `main` 切出
`upstream/master`	RuoYi 官方主干	❌ 否	❌ 否	官方仓库(只读)

分支生命周期图

复制代码

upstream/master ──┐
                  ├──► main ──► 生产环境
                  │     ▲
                  │     │ hotfix 合回
                  │     │
                  └──► dev ──► feature/xxx
                           ▲
                           │ merge 回 dev
                           │
                      feature/xxx

二、仓库初始化(仅首次执行)

1. 克隆自己的仓库

bash 复制代码

# username 你自己的账号名
git clone https://gitcode.com/username/my-project.git
cd my-project

2. 关联上游 RuoYi 官方仓库

bash 复制代码

git remote add upstream https://gitcode.com/yangzongzhuan/RuoYi-Vue3.git

3. 设置只拉取 master 分支(⚠️ 只执行一次)

bash 复制代码

git config remote.upstream.fetch +refs/heads/master:refs/remotes/upstream/master
# 其他分支，修改master->其他分支名称

⚠️ 确认只配置了一条 fetch 规则，可用以下命令检查：
bash 复制代码
git config --get-all remote.upstream.fetch
如果输出多于一行，用 git config --unset-all 清掉后重新设置。

4. 初始化 main 分支(对齐官方基线)

bash 复制代码

git fetch upstream
git checkout -b main upstream/master
git push -u origin main

✅ 使用 checkout -b 而非 reset --hard，保证历史可追溯。

5. 创建 dev 分支

bash 复制代码

git checkout -b dev
git push -u origin dev

6. 打上游锚点标签

bash 复制代码

git tag upstream/master-init
git push --tags

三、日常业务开发流程

1. 从 dev 切功能分支

bash 复制代码

git checkout dev
git pull origin dev
git checkout -b feature/user-module

2. 开发中

bash 复制代码

# 编码...
git add .
git commit -m "feat: 新增用户模块"

3. 合并回 dev(推荐通过 MR / PR)

bash 复制代码

git checkout dev
git merge --no-ff feature/user-module
git push origin dev

--no-ff 保留分支合并记录，方便回溯。

4. 清理已合并的功能分支

bash 复制代码

git branch -d feature/user-module
git push origin --delete feature/user-module

Commit Message 规范

前缀	含义	示例
`feat:`	新功能	`feat: 新增角色权限接口`
`fix:`	Bug 修复	`fix: 修复菜单缓存导致的显示异常`
`refactor:`	重构(非功能变更)	`refactor: 拆分用户服务层`
`docs:`	文档变更	`docs: 更新接口文档`
`chore:`	构建/工具变更	`chore: 升级 element-plus 版本`
`hotfix:`	紧急修复	`hotfix: 修复登录鉴权漏洞`

四、同步 RuoYi 上游更新(核心流程)

⚠️ 上游更新只进 dev，绝不直接合入 main

完整步骤

bash 复制代码

# 1️⃣ 拉取上游最新代码
git fetch upstream

# 2️⃣ 打上次同步锚点(方便回溯)
git tag upstream/master-last-sync

# 3️⃣ 切换到 dev
git checkout dev

# 4️⃣ 合并上游更新(冲突只在这里解决)
git merge upstream/master

# 5️⃣ 解决冲突
# 🔥 重点检查：ruoyi-common、ruoyi-admin、SQL 文件、配置文件

# 6️⃣ 运行测试(前端 / 后端 / 接口)
# ✅ 确保编译通过、核心流程可用

# 7️⃣ 提交合并结果
git add .
git commit -m "chore: 同步 RuoYi upstream/master 至 xxx 版本"

# 8️⃣ 推送 dev
git push origin dev

上游同步频率建议

场景	建议频率
官方有安全更新	立即同步
官方有功能更新	评估后同步
常规维护	每月一次

冲突高发区域(RuoYi 特有)

文件 / 目录	冲突原因	处理建议
`ruoyi-admin/src/main/resources/application.yml`	配置项变更	保留自定义配置，合入官方新增项
`ruoyi-common/**`	公共工具类变更	谨慎合并，检查业务依赖
`sql/`	数据库脚本更新	手写增量脚本，不要直接覆盖
`package.json` / `pom.xml`	依赖版本升级	评估兼容性后再升级

五、发布到生产(main)

标准发布流程

bash 复制代码

# 1️⃣ 确保 dev 已通过测试
git checkout dev
git pull origin dev

# 2️⃣ 切换到 main
git checkout main
git pull origin main

# 3️⃣ 合并 dev
git merge --no-ff dev

# 4️⃣ 打版本标签(强烈建议)
git tag -a v1.3.0-based-ruoyi-master -m "生产发布 v1.3.0，基于 RuoYi master"

# 5️⃣ 推送
git push origin main
git push --tags

版本号命名规范

复制代码

v{主版本}.{次版本}.{修订号}-based-ruoyi-master

示例：
v1.0.0-based-ruoyi-master
v1.3.0-based-ruoyi-master
v2.0.0-based-ruoyi-master

发布检查清单

dev 分支所有功能已测试通过
上游同步冲突已全部解决
数据库增量脚本已准备
配置文件已更新(生产环境)
前端构建产物已验证
版本标签已打

六、紧急修复(hotfix)

bash 复制代码

# 1️⃣ 从 main 切出 hotfix 分支
git checkout main
git pull origin main
git checkout -b hotfix/login-bug

# 2️⃣ 修复代码
# 🔧 编码...
git add .
git commit -m "hotfix: 修复登录异常"

# 3️⃣ 合入 main
git checkout main
git merge --no-ff hotfix/login-bug
git push origin main

# 4️⃣ 打紧急修复标签
git tag -a v1.3.1-hotfix-login -m "紧急修复：登录异常"
git push --tags

# 5️⃣ 同步回 dev(重要！否则下次发布会丢失修复)
git checkout dev
git merge main
git push origin dev

# 6️⃣ 清理
git branch -d hotfix/login-bug
git push origin --delete hotfix/login-bug

七、标签管理规范

标签类型

类型	命名格式	用途
生产版本	`v1.3.0-based-ruoyi-master`	标记每次生产发布
上游锚点	`upstream/master-YYYY-MM-DD`	标记每次同步上游的时间点
紧急修复	`v1.3.1-hotfix-xxx`	标记紧急修复发布

查看标签

bash 复制代码

# 查看所有标签
git tag

# 查看标签详情
git show v1.3.0-based-ruoyi-master

八、常用命令速查表

远程管理

bash 复制代码

# 查看远程仓库
git remote -v

# 查看 upstream fetch 配置
git config --get-all remote.upstream.fetch

# 查看上游分支列表
git ls-remote --heads upstream

分支管理

bash 复制代码

# 查看本地分支
git branch

# 查看所有分支(含远程)
git branch -a

# 查看分支追踪关系
git branch -vv

同步与回溯

bash 复制代码

# 拉取上游
git fetch upstream

# 查看当前分支领先/落后情况
git status

# 查看会引入的提交
git log --oneline HEAD..upstream/master

# 查看 reflog(误操作后找回提交)
git reflog

安全确认(执行危险操作前必跑)

bash 复制代码

git status
git diff --stat
git log --oneline -5

九、禁忌与红线

❌ 禁止操作	原因
直接向 `main` 提交代码	main 只接受来自 dev / hotfix 的合并
在 `main` 上开发功能	main 必须随时可发布
`git push -f` 到 `main` / `dev`	破坏团队历史，除非全员确认
跳过 dev 直接把上游合进 main	没有测试缓冲，极其危险
忘记把 hotfix 同步回 dev	下次发布会丢失修复
用 `reset --hard` 而不先备份分支	可能丢失未推送的提交
同时配置多条 upstream fetch 规则	后者覆盖前者，导致拉取的分支不符合预期

十、团队协作约定

所有功能开发必须在 feature/ 分支上进行
合并到 dev 必须通过 MR / PR + Code Review
每次同步上游后必须跑全套测试
数据库变更必须提供增量 SQL 脚本
敏感配置(密钥、数据库连接)不入库，使用环境变量或配置中心
每周同步一次 upstream 状态，评估是否需要升级

附录：完整初始化一键脚本

bash 复制代码

#!/bin/bash
# init-ruoyi-fork.sh

set -e

echo "📦 克隆仓库..."
git clone https://gitcode.com/username/my-project.git
cd my-project

echo "🔗 关联上游..."
git remote add upstream https://gitcode.com/yangzongzhuan/RuoYi-Vue3.git

echo "⚙️ 设置只拉取 master..."
git config remote.upstream.fetch +refs/heads/master:refs/remotes/upstream/master

echo "📥 拉取上游..."
git fetch upstream

echo "🌿 初始化 main..."
git checkout -b main upstream/master
git push -u origin main

echo "🌿 创建 dev..."
git checkout -b dev
git push -u origin dev

echo "🏷️ 打锚点标签..."
git tag upstream/master-init
git push --tags

echo "✅ 初始化完成！"

📌 最后提醒 ：二开的核心原则是 「官方代码和业务代码分离」------能不改官方文件就别改，必须改的做好记录，这样每次同步上游才会轻松。