30、综合实战：从零搭建一个开源项目的Git工作流

说实话，讲到这里，我觉得是时候把前面所有东西串起来了。

你可能会问：学了那么多分支策略、CI/CD、PR模板，到底怎么用在一个真实项目里？

好，今天我们就从零开始，搭一个完整的开源项目Git工作流。我会带着你一步步走完整个过程。

一、项目初始化：先把地基打牢

我个人习惯，新建一个开源项目时，第一件事不是写代码，而是搭好Git仓库的结构。

# 创建项目目录
mkdir my-open-source-project
cd my-open-source-project

# 初始化Git仓库
git init

# 创建主分支
git checkout -b main

# 创建第一个提交
echo "# My Open Source Project" > README.md
git add .
git commit -m "chore: initial commit with README"

嗯，这里有个小细节。我建议你一开始就把 main 作为默认分支，而不是 master。GitHub 从 2020 年开始就已经默认用 main 了，咱们也跟上节奏。

二、分支策略：选对模型，少走弯路

分支策略怎么选？说白了，就看你团队规模和发布频率。

我个人最常用的是 GitHub Flow 的变体——简单、直接、适合开源项目。

为什么不用 Git Flow 那套完整的？我在几个开源项目里试过，说实话，hotfix 和 support 分支对大多数项目来说太冗余了。你想想看，一个 3-5 人的开源项目，搞那么多分支，反而增加管理成本。

三、贡献指南：让新人少问问题

开源项目最怕什么？最怕有人提了一堆乱七八糟的 PR，你还得一个个去解释「为什么不收」。所以，CONTRIBUTING.md 必须写清楚。

我一般会在项目根目录放一个 CONTRIBUTING.md，内容大概这样：

# 贡献指南

感谢你考虑为本项目贡献代码！

## 分支规范
- 新功能：从 `develop` 拉取 `feature/功能名称`
- Bug修复：从 `develop` 拉取 `fix/问题描述`
- 发布：从 `develop` 拉取 `release/版本号`

## 提交信息格式
我们使用 Conventional Commits：
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- refactor: 重构
- test: 测试相关
- chore: 构建/工具

## 开发流程
1. Fork 本仓库
2. 创建你的功能分支
3. 提交代码（遵循提交规范）
4. 推送到你的 Fork
5. 发起 Pull Request 到 `develop` 分支

四、PR模板：标准化你的代码审查

PR模板这东西，说白了就是让提 PR 的人别漏掉关键信息。我在 .github/PULL_REQUEST_TEMPLATE.md 里放这个：

## 描述
请简要描述这个 PR 做了什么。

## 关联 Issue
Fixes #(issue编号)

## 变更类型
- [ ] 新功能 (feat)
- [ ] Bug修复 (fix)
- [ ] 文档更新 (docs)
- [ ] 重构 (refactor)
- [ ] 测试 (test)

## 测试情况
- [ ] 本地测试通过
- [ ] 新增了单元测试
- [ ] 所有 CI 检查通过

## 截图（如适用）

你想想看，如果没有模板，提 PR 的人可能就写一句 "修复了bug"。有了模板，他至少得想想：我改了啥？测试了没？关联哪个 issue？

五、CI/CD配置：自动化解放双手

CI/CD 这块，我个人推荐 GitHub Actions，因为和 GitHub 集成得最好，配置也简单。

在 .github/workflows/ci.yml 里配置：

name: CI Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [develop]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: 安装依赖
        run: npm ci
      - name: 运行测试
        run: npm test
      - name: 代码检查
        run: npm run lint

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: 构建
        run: npm run build

六、版本发布流程：从开发到上线

版本发布这块，我习惯用 语义化版本（SemVer）：主版本.次版本.修订号。

版本号	变更类型	示例
主版本	不兼容的API变更	1.0.0 → 2.0.0
次版本	向下兼容的新功能	1.0.0 → 1.1.0
修订号	向下兼容的bug修复	1.0.0 → 1.0.1

发布流程大概是这样的：

1. 从 develop 拉出 release/1.1.0 分支
2. 在这个分支上只做 bug 修复，不加新功能
3. 测试通过后，合并到 main 并打上 tag
4. 把 main 上的改动合并回 develop

# 创建发布分支
git checkout -b release/1.1.0 develop

# 修复发布前的bug
git commit -m "fix: correct login timeout issue"

# 合并到main并打tag
git checkout main
git merge --no-ff release/1.1.0
git tag -a v1.1.0 -m "Release version 1.1.0"

# 合并回develop
git checkout develop
git merge --no-ff release/1.1.0

# 删除发布分支
git branch -d release/1.1.0

七、避坑指南：我踩过的那些坑

做了这么多年开源项目，有些坑我不得不提：

• 不要直接在 main 上开发——我曾经图省事，直接在 main 上改了个小bug，结果忘了合并回 develop，后面发布时那个bug又出现了。
• PR 一定要有 review——哪怕是一个人维护的项目，也建议找个朋友帮忙 review。自己看自己的代码，很容易忽略问题。
• CI 失败不要合并——这是铁律。CI 没过，说明代码有问题，合并进去只会让问题扩散。
• 提交信息要规范——别小看这个，规范的提交信息能帮你自动生成 changelog。

好了，这就是我从零搭建开源项目Git工作流的完整流程。你可以直接照着这个模板去搭自己的项目，遇到问题随时调整。毕竟，没有完美的流程，只有适合自己团队的流程。

---

公众号:蓝海资料掘金营，微信deep3321