GitHub 使用規範完全指南:從提交到協作的最佳實踐

前言#

如果你正在和團隊一起使用 GitHub 管理代碼，或者參與開源項目貢獻，你一定遇到過這樣的困惑 Message 該怎麼寫？分支該如何管理？Pull Request 要遵循什麼規則？這些看似簡單的問題，實際上直接影響著項目的可維護性和團隊協作效率。

開發團隊需要通過規範的工作流程來管理代碼版本，本文將系統地介紹 GitHub 的使用規範，包括 Commit 提交規範、分支管理策略、Pull Request 流程以及項目文檔規範。無論你是剛接觸 GitHub 的新手，還是想優化團隊協作流程的開發者，都能從中找到實用的建議。

讀完這篇文章，你將掌握:

如何寫出清晰規範的 Commit Message
如何選擇適合團隊的分支管理策略
如何正確地發起和審查 Pull Request
如何建立規範的開源項目結構

Commit Message 提交規範#

為什麼需要規範的 Commit Message#

通過閱讀提交信息就可以在不用閱讀代碼的情況下大概了解此版本的改動內容。規範的提交信息不僅幫助團隊成員理解代碼變更，還能:

快速瀏覽項目歷史，了解功能演進
自動生成 CHANGELOG 文檔
方便追蹤 bug 來源和功能實現
提升代碼審查效率

Angular 規範#

Angular 提交規範是最早被廣泛採用的一套規範，後來演化出了更通用的 Conventional Commits；現在大家通常說的 “業界標準” 更偏向後者。

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

<body>

<footer>

結構說明:

Header (必填): 包含 type、scope (可選) 和 subject
Body (可選): 對本次提交的詳細描述
Footer (可選): 關聯 Issue 或說明不兼容變動

Header 部分詳解#

Type (類型) - 必填

用於說明本次提交的類別，常用類型包括:

feat: 新增功能 (feature)
fix: 修復 bug
docs: 文檔變更 (documentation)
style: 代碼格式調整 (不影響代碼運行)
refactor: 重構 (既不是新增功能，也不是修改 bug)
perf: 性能優化
test: 增加測試
chore: 構建過程或輔助工具的變動
ci: CI 配置文件和腳本的變動
build: 影響構建系統或外部依賴的變更
revert: 回滾某次已經提交的變更

Scope (範圍) - 可選

用於說明 commit 影響的範圍，比如數據層、控制層、視圖層等等，視項目不同而不同。例如、Service、API、UI、Database 等。

Subject (主題) - 必填

是對 commit 的一個簡短的描述，一般不超過 50 個字符。書寫要求:

使用祈使語氣、現在時態：用 "change" 而非 "changed" 或 "changes"
首字母小寫
結尾不加句號

Body 部分#

Body 用於對本次提交進行詳細描述，說明:

為什麼需要這次改動
改動的影響範圍
與之前行為的對比

一行不超過 72 個字符。

Footer 部分#

Footer 主要用於兩種情況:

1. 關閉 Issue

使用關鍵字可以自動關閉 Issue:

Closes #123 - 關閉單個 Issue
Closes #123, #456 - 關閉多個 Issue
其他關鍵字:Fixes、Resolves、Close、Fix、Resolve

2. 不兼容變動

如果當前代碼與上個版本不兼容，Footer 需要以 BREAKING CHANGE: 開頭，說明變動描述、變動理由和遷移方法。

實際示例#

簡單示例:

feat(user): add user login feature

fix(api): resolve timeout issue in payment module

docs(readme): update installation guide

完整示例:

feat(shopping-cart): add product quantity selector

Allow users to change product quantity directly in the cart page.
This improves user experience by reducing the number of clicks needed.

Closes #234

包含不兼容變動:

refactor(api): change authentication method

BREAKING CHANGE: The authentication API now requires OAuth 2.0 instead of API keys.
All existing integrations need to be updated to use the new OAuth flow.
See migration guide: docs/migration-oauth.md

使用工具保證規範#

Commitizen - 交互式提交工具

Commitizen 可以提供友好的交互界面，幫助你生成規範的提交信息。

安裝和配置:

# 安裝 Commitizen
npm install --save-dev commitizen

# 安裝 Angular 規範適配器
npm install --save-dev cz-conventional-changelog

# 初始化
npx commitizen init cz-conventional-changelog --save-dev --save-exact

使用方法:

# 使用 git cz 代替 git commit
git add .
git cz

Commitlint - 提交信息校驗工具

可以幫助我們 lint commit messages, 如果我們提交的不符合指定的規範，會直接拒絕提交。

安裝配置:

# 安裝
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# 創建配置文件
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

結合 Husky 使用:

# 安裝
npm install husky --save-dev
npx husky init

# 添加 commit-msg 鉤子
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

這樣每次提交時，如果不符合規範就會被拒絕。

分支管理策略#

為什麼需要分支管理策略#

如果你不加注意，很可能會留下一个枝節蔓生、四處開放的版本庫，到處都是分支，完全看不出主幹發展的脈絡。合理的分支策略能夠:

隔離不同功能的開發，避免相互干擾
支持並行開發和快速迭代
保證主分支代碼的穩定性
方便版本發布和回滾

Git Flow - 經典的分支管理模型#

Git Flow 是最早被系統化提出、影響力很大的工作流之一，適合有明確發布周期的項目。

主要分支

1. main 分支

永遠保持穩定可發布狀態
只能通過合併其他分支來更新
每次合併都要打上版本標籤 (tag)

2. develop 分支

日常開發的主分支
包含下次發布的最新開發成果
當代碼達到穩定狀態時，合併到 main 並發布

輔助分支

1. Feature 分支 (功能分支)

Feature 分支用來做分模块功能開發，建議命名為 feature-xxx。

從 develop 分支創建
開發完成後合併回 develop
命名規則:feature/功能名稱 或 feature-功能名稱
開發完成後刪除

# 創建功能分支
git checkout -b feature/user-profile develop

# 開發完成後合併
git checkout develop
git merge --no-ff feature/user-profile
git branch -d feature/user-profile
git push origin develop

2. Release 分支 (預發布分支)

Release 分支用來做版本發布的預發布分支，建議命名為 release-xxx。

從 develop 分支創建
用於發布前的測試和小 bug 修復
測試通過後合併到 main 和 develop
命名規則:release/版本號 或 release-版本號

# 創建預發布分支
git checkout -b release/1.2.0 develop

# 修改版本號等準備工作
# 進行測試和 bug 修復

# 合併到 main
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"

# 合併回 develop
git checkout develop
git merge --no-ff release/1.2.0

# 刪除分支
git branch -d release/1.2.0

3. Hotfix 分支 (熱修復分支)

Hotfix 分支是用來做線上的緊急 bug 修復的分支，建議命名為 hotfix-xxx。

從 main 分支創建
修復完成後合併到 main 和 develop
合併到 main 時打上修復版本標籤
命名規則:hotfix/問題描述 或 hotfix-問題描述

# 創建熱修復分支
git checkout -b hotfix/critical-bug main

# 修復 bug
# ...

# 合併到 main
git checkout main
git merge --no-ff hotfix/critical-bug
git tag -a v1.2.1 -m "Hotfix for critical bug"

# 合併到 develop
git checkout develop
git merge --no-ff hotfix/critical-bug

# 刪除分支
git branch -d hotfix/critical-bug

GitHub Flow - 簡化的工作流#

GitHub Flow 的優點是比 Git Flow 簡單，適合 CI/CD（持續集成 / 持續部署）流程的項目。

基本原則:

main 分支永遠是可部署的
開發新功能時，從 main 創建描述性的分支
定期提交到本地分支，並推送到遠程同名分支
需要幫助或準備合併時，發起 Pull Request
經過審查和測試後，合併到 main
合併後立即部署

工作流程:

# 1. 創建功能分支
git checkout -b add-user-avatar main

# 2. 進行開發並提交
git add .
git commit -m "feat: add user avatar upload"

# 3. 推送到遠程
git push origin add-user-avatar

# 4. 在 GitHub 上發起 Pull Request

# 5. 代碼審查通過後,在 GitHub 上合併到 main

# 6. 合併後立即部署

GitLab Flow - 環境導向的工作流#

GitLab Flow 比 GitHub Flow 多了 staging、production 等分支。它結合了 Git Flow 和 GitHub Flow 的優點，更關注持續集成和持續部署。

核心思想:

使用 feature 分支開發
通過 Code Review 後合併到 main
main 作為開發主分支
為不同環境創建對應分支、production
代碼按環境依次推進 → staging → production

適用場景:

需要多環境部署的項目
強調持續集成和持續部署
需要在不同環境驗證代碼的項目

如何選擇分支策略#

選擇 Git Flow 如果:

項目有明確的版本發布周期
需要同時維護多個版本
團隊規模較大，分工明確
對代碼質量要求嚴格

選擇 GitHub Flow 如果:

項目需要持續部署
團隊規模較小，溝通順暢
希望保持簡單的工作流
不需要維護多個生產版本

選擇 GitLab Flow 如果:

需要在多個環境中驗證代碼
強調 CI/CD 流程
需要環境隔離和逐步推進

Pull Request 最佳實踐#

什麼是 Pull Request#

Pull Request 是一種通知機制。你修改了他人的代碼，將你的修改通知原來的作者，希望他合併你的修改，這就是 Pull Request。

PR 的基本原則#

一個 PR 只圍繞一件事，避免過大的 PR。具體來說:

1. 單一職責

一個 PR 只解決一個問題或實現一個功能
不要在同一個 PR 中混入多個不相關的改動
如果需要多個功能，分成多個 PR 提交

2. 控制 PR 大小

文件改變最好少於 12 個文件 (排除構建產生的文件)
代碼行數控制在合理範圍 (建議不超過 400 行)
過大的 PR 難以審查，容易引入問題

3. 清晰的描述

PR 標題和描述要清晰明確:

標題格式:[類型] + 動詞 + 名詞 + [形容詞] + [名詞]
例如:修復 Collapse 組件無法展開的問題、新增用戶頭像上傳功能

如何發起 Pull Request#

標準流程:

Fork 目標倉庫(如果是外部項目)
Clone 到本地

git clone https://github.com/你的用戶名/項目名.git
cd 項目名

創建功能分支

git checkout -b feature/my-feature

進行開發並提交

git add .
git commit -m "feat: add new feature"

推送到遠程

git push origin feature/my-feature

在 GitHub 上創建 Pull Request
- 進入你的 Fork 倉庫
- 點擊 "Compare & pull request"
- 選擇正確的 base 分支 (通常是 develop 或 main)
- 填寫 PR 標題和描述
- 提交 Pull Request

PR 描述模板#

好的 PR 描述應該包含以下內容:

## 改動說明
簡要描述本次 PR 的目的和改動內容。

## 改動類型
- [ ] Bug 修復
- [ ] 新功能
- [ ] 代碼重構
- [ ] 文檔更新
- [ ] 性能優化
- [ ] 其他(請說明):

## 相關 Issue
Closes #123
Relates #456

## 測試說明
- 測試用例已添加/更新
- 本地測試通過
- 所有 CI 檢查通過

## 截圖/錄屏
(如果有 UI 變動,請提供截圖或錄屏)

## 額外說明
(其他需要審查者注意的事項)

代碼審查要點#

作為 PR 提交者:

提交前自己先審查一遍代碼
確保代碼符合項目的編碼規範
所有測試都要通過
及時回應審查意見
不要在 PR 中修復審查時發現的無關問題

作為代碼審查者:

關注代碼邏輯和設計是否合理
檢查是否有潛在的 bug 或安全問題
確保代碼符合團隊規範
提供建設性的反饋意見
及時響應，不要讓 PR 長時間懸而未決

常見問題處理#

1. PR 與主分支衝突

# 更新主分支
git checkout main
git pull origin main

# 切回功能分支並 rebase
git checkout feature/my-feature
git rebase main

# 解決衝突後繼續
git add .
git rebase --continue

# 強制推送(因為改變了提交歷史)
git push origin feature/my-feature --force

2. 需要修改已提交的 PR

直接在原分支上繼續提交即可，GitHub 會自動更新 PR:

git add .
git commit -m "fix: address review comments"
git push origin feature/my-feature

3. PR 被合併後的清理

# 刪除本地分支
git branch -d feature/my-feature

# 刪除遠程分支
git push origin --delete feature/my-feature

# 更新本地主分支
git checkout main
git pull origin main

GitHub 項目規範#

必備文件#

一個規範的 GitHub 項目應該包含以下文件:

1. README.md

這是項目的門面，README 文件不僅要簡潔明了地說明項目的目的和功能，還應包含安裝指南、使用方式、貢獻指南、許可信息。

基本結構:

# 項目名稱

簡短的項目描述

## 功能特性
- 特性 1
- 特性 2

## 快速開始

### 環境要求
- Node.js >= 14
- npm >= 6

### 安裝
npm install

### 使用

npm start

## 文檔

詳細文檔請查看 [文檔目錄](./docs)

## 貢獻指南

請查看 [CONTRIBUTING.md](./CONTRIBUTING.md)

## 許可證

[MIT](./LICENSE)

2. .gitignore

每個存儲庫中都必須使用 .gitignore 文件來忽略預定義的文件和目錄。

建議使用 gitignore.io 生成針對你的技術棧的 .gitignore 文件。

3. LICENSE

選擇合適的開源許可證:

MIT - 最寬鬆，允許商業使用
Apache 2.0 - 提供專利保護
GPL - 要求衍生作品也開源
BSD - 類似 MIT, 但有一些限制

4. CONTRIBUTING.md

說明如何為項目做貢獻:

如何提交 Issue
如何提交 Pull Request
代碼規範要求
開發環境搭建
測試要求

5. CHANGELOG.md

記錄項目的版本變更歷史:

# Changelog

## [1.2.0] - 2024-12-06

### Added
- 新增用戶頭像上傳功能

### Fixed
- 修復登錄頁面樣式問題

### Changed
- 優化數據庫查詢性能

## [1.1.0] - 2024-11-15
...

其他最佳實踐#

1. 保護主分支

主分支中的任何內容都應該是可部署的，所以不應該直接在默認分支上提交代碼。

在 GitHub 倉庫設置中:

Settings → Branches → Branch protection rules
添加規則保護 main 分支
要求 PR review 後才能合併
要求 CI 檢查通過
禁止強制推送

2. 使用 Issue 模板

創建 .github/ISSUE_TEMPLATE 目錄，添加不同類型的 Issue 模板:

bug_report.md - Bug 報告模板
feature_request.md - 功能請求模板

3. 配置 Code Owners

使用 codeowners 功能可以定義哪些團隊和人員被自動選為存儲庫的 reviewer。

創建 .github/CODEOWNERS 文件:

# 默認所有人
* @team-lead

# 前端代碼
/src/frontend/ @frontend-team

# 後端代碼
/src/backend/ @backend-team

# 文檔
/docs/ @doc-team

4. 归档不再维护的仓库

对于不再积极开发的存储库，最佳实践是归档这些存储库，设置为只读模式。

在仓库设置中选择 "Archive this repository"。

5. 避免提交敏感信息

千万不要将任何 secret 提交到代码中。可以使用从安全存储外部注入的环境变量。

使用环境变量或配置文件管理敏感信息:

数据库密码
API 密钥
私有令牌
SSH 密钥

常見問題與解決方案#

提交了錯誤的 Commit 怎麼辦？#

修改最近一次提交:

# 修改提交信息
git commit --amend -m "新的提交信息"

# 添加遺漏的文件
git add forgotten_file
git commit --amend --no-edit

撤銷已推送的提交:

公共分支優先用 git revert，reset --hard + --force 僅用於個人分支或極特殊場景。

# 軟重置(保留改動)
git reset --soft HEAD~1
git push origin branch-name --force

# 硬重置(丟弃改动)
# ⚠ 僅限你自己控制的特性分支，不要對共享的 main / develop 這樣做
git reset --hard HEAD~1
git push origin branch-name --force

如何合併多個 Commit?#

使用交互式 rebase:

# 合併最近 3 個 commit
git rebase -i HEAD~3

# 在編輯器中,將要合併的 commit 前的 pick 改為 squash(或 s)
# 保存退出後,編輯合併後的 commit message

分支衝突如何解決？#

# 1. 更新主分支
git checkout main
git pull origin main

# 2. 回到功能分支
git checkout feature-branch

# 3. 合併或 rebase
git merge main
# 或者
git rebase main

# 4. 解決衝突
# 編輯衝突文件,刪除衝突標記

# 5. 標記為已解決
git add .

# 6. 繼續合併或 rebase
git merge --continue
# 或者
git rebase --continue

# 7. 推送
git push origin feature-branch --force-with-lease

如何配置 Git 用戶信息？#

確保你的 Git 客戶端配置了正確的電子郵件地址並鏈接到了你的 GitHub 用戶。

# 全局配置
git config --global user.name "你的名字"
git config --global user.email "你的郵箱@example.com"

# 僅當前項目配置
git config user.name "你的名字"
git config user.email "你的郵箱@example.com"

# 查看配置
git config --list

寫在最後#

GitHub 使用規範看似繁瑣，但實際上是保證項目質量和團隊協作效率的重要基礎。從我的經驗來看，一個團隊是否有清晰的 Git 規範，直接體現在項目的可維護性上。

剛開始推行這些規範時，可能會覺得增加了工作量，但當你習慣之後，會發現這些規範大大減少了後期維護成本。尤其是當你需要回溯某個 bug 的引入時間，或者需要快速了解某個功能的實現邏輯時，規範的 Commit Message 和清晰的分支歷史會讓你事半功倍。

我的建議是:

從小處著手 - 先從規範 Commit Message 開始，逐步引入其他規範
工具輔助 - 使用 Commitizen、Commitlint 等工具自動化檢查
團隊共識 - 規範要全員認同，而不是強制推行
持續優化 - 根據團隊實際情況調整規範，不必完全照搬
以身作則 - 作為 Leader 或老成員，要率先遵守規範

記住，規範的目的是提升效率，而不是製造障礙。選擇適合自己團隊的規範，並堅持執行，你會看到代碼質量和協作效率的顯著提升。

如果你在實踐中遇到問題，或者有更好的實踐經驗，歡迎在評論區交流討論。

十点还有几分钟