本篇重點
- Conventional Commits 是建立在 Git Commit Message 上的輕量規範，讓 Commit 同時具有人類與機器可讀的結構
- 基本格式為
<type>[optional scope]: <description>，body與footer皆為選填 - 彙整主要 commit type 類型及其適用情境
- Conventional Commits 能讓 Commit History 更容易閱讀，還能提供 Changelog、Semantic Versioning、Release 與 CI/CD 自動化所需的結構化資訊
Conventional Commits 核心結構
核心欄位說明：
| 欄位 | 必要性 | 說明 |
|---|---|---|
type | 必要 | 描述 Commit 的變更類型 |
scope | 選填 | 描述變更影響的範圍或區域 |
description | 必要 | 簡短描述變更內容 |
body | 選填 | 詳細說明變更原因以及與先前行為的對比 |
footer | 選填 | 說明變更額外資訊 |
Type 類型定義
Conventional Commits 並沒有強制所有專案必須使用一組完整固定的 Type，feat 與 fix 是規範中具有明確定義的兩個核心 Type。docs、refactor、test、chore 等則是目前非常常見的實務分類。
| Type | 定義與用途 | 範例 |
|---|---|---|
| feat | 新增功能（Feature） | feat: add user login |
| fix | 修復 Bug | fix: handle invalid token |
| docs | 僅變更文件內容 | docs: update API guide |
| refactor | 重構程式碼（既不新增功能也不修復 Bug） | refactor: simplify auth flow |
| test | 新增或修整測試案例 | test: add login tests |
| chore | 維護性工作 | chore: update dependencies |
| style | 不影響程式碼邏輯的格式調整（空格、縮排等） | style: format source files |
| perf | 提升效能的程式碼變更 | perf: reduce query overhead |
| build | 影響建置系統或外部依賴項的變更 | build: update webpack |
| ci | 變更 CI 設定檔或腳本 | ci: update GitHub Actions |
健忘筆記
style 在 Conventional Commits 中通常代表不影響程式語意的格式調整，例如空白、排版或格式化，而不是 UI Style 修改，UI Style 新增/修改應該使用 feat。
Scope 修改範圍
描述變更影響的範圍或區域
1 | feat(auth): add OAuth login |
適合在大型專案或模組較多時使用；小型專案也可以省略。
1 | feat: add OAuth login |
Description 描述變更
負責描述「這次 Commit 改了什麼」，保持短而明確的內容
1 | fix: handle expired access token |
避免使用無法判斷變更內容的描述
1 | fix: update code |
Body 補充原因與背景
Description 不足以說明修改原因時，增加 Body 補充說明
1 | fix(auth): reject expired access tokens |
Footer 記錄額外資訊
說明 commit 額外資訊，標註破壞性變更（Breaking Changes）、記錄 Issue/PR 關聯或其他 Metadata：
1 | fix(api): handle invalid request payload |
也可以記錄 Breaking Change：
1 | feat(api): change authentication response |
健忘筆記
GitHub 提供 Reference System 透過簡單的語法讓 Issue、Pull Request、Commit 建立關聯。更多相關資訊可以查看【GitHub】解析 Reference System：Issue、Pull Request、Commit 如何建立關聯
破壞性變更標示方式
當變更包含打破向下相容性（Breaking Changes）的重大修改時，必須在 Commit 訊息中明確標示，以利版本自動升級判定（MAJOR），兩種方法可同時使用也可擇一使用。
驚嘆號標示（簡短表示）
在 type（或 scope）之後、冒號之前的位置加上 !。
1 | feat(api)!: remove legacy user authentication endpoint |
Footer 頁腳標示（詳細表示）
在 Body 後方空一行，於 Footer 開頭使用大寫 BREAKING CHANGE:，後方緊接變更的詳細說明或遷移指南。
1 | feat(api): update user authentication signature |
結論
Conventional Commits 透過統一的結構限制，降低了團隊成員理解變更紀錄的認知成本。更重要的是，格式化的 Commit Message 成為現代自動化工具鏈的關鍵基礎，讓專案的版本號變更、Changelog 生成與 Release 流程能夠無縫整合到 CI/CD Pipeline，提升軟體交付的精確度與效率！
