x-server-mobile/docs/guides/GIT_WORKFLOW.md

Git 工作流程

分支说明

分支	用途	部署环境
master	生产分支	线上生产环境 (45.153.130.80)
develop	开发集成分支	测试/预发布环境
feature/*	个人功能分支	本地开发环境

分支结构

                    master (生产)
                       ↑
                    发布合并
                       ↑
                   develop (开发)
                       ↑
                    功能合并
                       ↑
    ┌──────────────┬────┴────┬──────────────┐
    ↓              ↓         ↓              ↓
feature/xxx-1  feature/xxx-2  feature/xxx-3  feature/xxx-4
 (个人A)       (个人B)       (个人A)        (个人B)

---

一、工作流程

1.1 开发新功能

从 develop 创建个人功能分支：

# 确保本地 develop 是最新的
git checkout develop
git pull origin develop

# 创建个人功能分支（命名规范：feature/功能名 或 feature/功能名-姓名首字母）
git checkout -b feature/user-login
# 或带姓名标识
git checkout -b feature/user-login-mzl

在功能分支上开发：

# 开发、提交
git add .
git commit -m "feat: add user login"
git push origin feature/user-login

# 继续开发...
git add .
git commit -m "fix: correct login error handling"
git push origin feature/user-login

1.2 功能开发完成

合并到 develop 进行团队测试：

# 1. 切换到 develop 并更新
git checkout develop
git pull origin develop

# 2. 合并功能分支（使用 --no-ff 保留合并历史）
git merge --no-ff feature/user-login -m "Merge feature/user-login into develop"

# 3. 推送到远程
git push origin develop

# 4. （可选）删除已合并的功能分支
git branch -d feature/user-login
git push origin --delete feature/user-login

1.3 发布到生产

从 develop 合并到 master：

# 1. 切换到 master 并更新
git checkout master
git pull origin master

# 2. 合并 develop（使用 --no-ff 保留合并历史）
git merge --no-ff develop -m "Release: merge develop into master"

# 3. 添加版本标签（可选）
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# 4. 推送到远程
git push origin master

1.4 生产服务器部署

ssh root@45.153.130.80
cd /opt/x-server-mobile
git pull origin master
docker restart x-server-backend
# 或
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d

---

二、分支命名规范

分支类型	命名格式	示例
功能分支	feature/功能名 或 feature/功能名-姓名	feature/user-login, feature/user-login-mzl
修复分支	fix/问题描述 或 fix/问题描述-姓名	fix/login-error, fix/login-error-mzl
热修复分支	hotfix/问题描述	hotfix/security-fix

---

三、前端部署

# 1. 切换到 master
git checkout master
git pull origin master

# 2. 构建前端
cd frontend
npm run build --mode production

# 3. 上传到服务器
rsync -avz --delete frontend/dist/ root@45.153.130.80:/www/sites/uniservice-mobile.hnxinyouhe.com/index/

---

四、提交信息规范

类型	说明	示例
feat	新功能	feat: add user login
fix	修复bug	fix: correct i18n loading
docs	文档变更	docs: update deployment guide
style	代码格式	style: format code
refactor	重构	refactor: simplify auth logic
test	测试相关	test: add login test
chore	构建/工具	chore: update dependencies

完整格式：

<type>(<scope>): <subject>

<body>

<footer>

示例：

feat(login): add feishu auto-login support

- Add H5 JSSDK integration
- Implement tt.requestAuthCode for silent login
- Add token auto-refresh on 401

Closes #123

---

五、快速发布脚本

5.1 功能合并到 develop

# 添加到 ~/.bashrc 或 ~/.zshrc
git-finish() {
    local branch=$(git branch --show-current)
    if [[ $branch != feature/* ]]; then
        echo "❌ 当前不在 feature 分支上"
        return 1
    fi

    echo "=== 合并 $branch 到 develop ==="
    git checkout develop && \
    git pull origin develop && \
    git merge --no-ff $branch -m "Merge $branch into develop" && \
    git push origin develop && \
    echo "✅ 完成，可删除功能分支: git branch -d $branch"
}

5.2 发布到 master

# 添加到 ~/.bashrc 或 ~/.zshrc
git-release() {
    echo "=== 发布 develop 到 master ==="
    git checkout master && \
    git pull origin master && \
    git merge --no-ff develop -m "Release: merge develop into master" && \
    git push origin master && \
    git checkout develop && \
    echo "✅ 发布完成，请部署生产环境"
}

---

六、协作场景

6.1 多人同时开发

时间线：
┌─────────────────────────────────────────────────────────────┐
│ A 开发 feature/login                                         │
│ B 开发 feature/dashboard                                     │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ A 完成，合并 feature/login 到 develop                        │
│ B 继续开发 feature/dashboard                                │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ B 完成，合并 feature/dashboard 到 develop                    │
│ (此时 develop 包含 A 和 B 的更改)                            │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 在 develop 上测试通过后，合并到 master 发布                  │
└─────────────────────────────────────────────────────────────┘

6.2 处理冲突

# 合并时遇到冲突
git checkout develop
git merge feature/login

# Git 提示冲突
# Auto-merging src/login.tsx
# CONFLICT (content): Merge conflict in src/login.tsx

# 手动解决冲突后
git add src/login.tsx
git commit -m "Merge feature/login into develop (resolved conflicts)"
git push origin develop

---

七、远程仓库

• 仓库地址：http://219.157.255.213:25311/xinyouhe/x-server-mobile.git
• 生产分支：master
• 开发分支：develop
• 个人分支：feature/*

---

八、最佳实践

✅ 推荐做法

1. 保持分支简短 - 功能分支完成后及时合并并删除
2. 频繁提交 - 小步提交，便于代码审查和回滚
3. 写好提交信息 - 清晰描述做了什么
4. 推送前先拉取 - 避免不必要的冲突
5. 代码审查 - 合并前让团队成员审查代码

❌ 避免做法

1. 直接在 master/develop 上开发 - 始终使用功能分支
2. 长时间不合并 - 功能分支会越来越难合并
3. 提交敏感信息 - 密钥、配置等不要提交
4. 强制推送 master/develop - 可能丢失他人代码

---

九、常用命令速查

# 查看分支状态
git status
git branch -vv

# 创建功能分支
git checkout develop && git pull
git checkout -b feature/xxx

# 合并功能分支
git checkout develop
git merge --no-ff feature/xxx

# 发布到生产
git checkout master
git merge --no-ff develop

# 删除已合并分支
git branch -d feature/xxx
git push origin --delete feature/xxx

# 查看差异
git diff develop master
git log --oneline --graph --all

---

最后更新: 2026-02-28