企业官网建设流程全解析

• 文档

慣例式提交（Conventional Commits）是一套作用於 Git 提交說明的輕量級慣例，它用簡單的規則集合建立明確、可讀且可被機器解析的提交歷史，並與語意化版本（SemVer）一一對應：feat對應次版本（MINOR）、fix對應修訂號（PATCH）、BREAKING CHANGE對應主版本（MAJOR）。本指南以本倉庫（conventionalcommits.org，即慣例式提交規範的官方開源倉庫）中 content/v1.0.0/index.zh-hant.md（1.0.0 正式版繁體中文翻譯）為主體，完整覆蓋提交訊息的結構、類型體系、作用範圍、頁腳（footer）慣例、RFC 2119 規範全文、官方範例與 FAQ，並結合倉庫的目錄結構、多語言配置與本地建置方式，讓你能在團隊中直接落地這套規範。

概述：什麼是慣例式提交

慣例式提交規範，是一種對提交說明的輕量慣例。它提供一些簡單的條件集合用於建立明確的提交歷史；這能讓自動化工具更容易撰寫。這份慣例能對應到 SemVer，透過在提交說明裡描述功能、修正以及重大變更。

其核心思想是：提交說明不只是寫給人看的備註，更是機器可讀的「版本演進訊號」。提交說明中描述的「功能、修正、重大變更」三類資訊，正是決定下一個發行版號該如何變動的依據。因此在 1.0.0 正式版中，規範明確規定提交說明必須依照以下結構建構：

<類型 type>[可選的作用範圍 scope]: <描述 description> [可選的正文 body] [可選的頁腳 footer]

提交應包含以下結構性元素，用以向使用這套函式庫的使用者溝通當時的意圖：

1. fix:為fix類型的提交，表示對程式修正了一個臭蟲（bug）（對應到語意化版本中的修訂號 PATCH）。
2. feat:為feat類型的提交，表示對程式增加了一個功能（對應到語意化版本中的次版本 MINOR）。
3. BREAKING CHANGE:重大變更，如果提交的頁腳以BREAKING CHANGE:開頭，或是在類型、作用範圍後有!，代表包含了重大 API 變更（對應到語意化版本中的主版本 MAJOR）。重大變更可以是任何類型提交的一部分。
4. 其他: 除fix:與feat:以外，其他的提交類型也是被允許的，例如 @commitlint/config-conventional（基於 Angular 慣例）中推薦的chore:、docs:、style:、refactor:、perf:、test:以及更多。

我們也推薦對那些沒有增加新功能或是修正臭蟲而是改善目前實作的提交使用improvement。請注意，這些類型在慣例式提交規範中並不是強制性的，且在語意化版本中也沒有隱含的作用（除非它們包含 BREAKING CHANGE）。

除了fix:與feat:之外也允許其他的類型，如（基於 Angular 慣例的）@commitlint/config-conventional 推薦使用build:與chore:、ci:、docs:、style:、refactor:、perf:、test:、等其他。也可以使用BREAKING CHANGE: <描述>之外的頁腳，並遵守類似 git trailer format（git interpret-trailers 慣例）的慣例。

追加類型並不被慣例式提交所束縛，並且不對語義化版本有任何隱藏的影響（但若包含 BREAKING CHANGE 則不在此限）。

提交的類型可以在括號內給予作用範圍，以提供額外的脈絡資訊。例如：feat(parser): add ability to parse arrays。

與 SemVer 的對應關係

慣例式提交與語意化版本（SemVer）的對應是這份規範最具實用價值的部分，也是自動化版本號升級工具的運作基礎：

從倉庫中可以進一步印證這套對應邏輯的「歷史演進」：在較早期的 content/v1.0.0-beta.4/index.md 中，!必須與BREAKING CHANGE: description頁腳同時出現；而在 1.0.0 正式版（本篇文章的主體）中，兩者被放寬為二選一的等價表達方式（見下方規範第 13 條）。

完整範例解析

規範原文提供了 7 組代表性範例，覆蓋了從最簡潔到最完整的提交說明形態。以下逐一解析。

1. 包含描述以及頁腳有重大變更的提交說明

feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files

此例展示了最常見的重大變更宣告方式：feat類型 + 正文後空一行 +BREAKING CHANGE:頁腳。頁腳中的描述說明了 API 行為的變化點（extends鍵的語義從「合併」改為「擴充」），這正是工具需要寫進 changelog 與 MAJOR 版本說明書的內容。

2. 包含用以提示重大變更的!的提交說明

feat!: send an email to the customer when a product is shipped

!緊鄰在冒號之前、位於類型之後，是 1.0.0 規範引入的前綴式重大變更標記。此例中沒有BREAKING CHANGE:頁腳——根據規範第 13 條，使用!後可省略頁腳，此時提交說明本身（描述）即應用來描述重大變更。

3. 包含作用範圍和提示重大變更的!的提交說明

feat(api)!: send an email to the customer when a product is shipped

作用範圍（scope）置於括號內、位於!之前，完整的前綴順序是：類型(作用範圍)!:。api表示這次變更影響的是 API 層面，為讀者與工具提供了額外的上下文。

4. 包含!以及頁腳有重大變更的提交說明

feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6.

此例同時使用了!前綴與BREAKING CHANGE:頁腳，屬於最「明顯」的重大變更宣告：前綴吸引注意力，頁腳給出完整描述。這是合法的寫法（頁腳可選），也常用於希望雙重強調的場合。

5. 不包含正文的提交說明

docs: correct spelling of CHANGELOG

最簡潔的提交：只有類型 + 描述，沒有作用範圍、正文與頁腳。docs類型表示純文件變更，對 SemVer 版本號沒有影響。

6. 包含作用範圍的提交說明

feat(lang): add polish language

lang作用範圍指明功能變更位於「語言支援」這塊程式區段，適用於大型 codebase 中定位改動位置。

7. 正文有多段落以及有多個頁腳的提交說明

fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123

這是最完整的提交形態，示範了三點關鍵規則：

• 正文由多個以換行分隔的段落組成，用來說明問題成因（racing 請求）與解決方案（request id + 最新請求參照）；
• 多個頁腳依次列出：Reviewed-by: Z（審閱者）與Refs: #123（關聯 issue/PR 編號）；
• 頁腳符記（token）Reviewed-by以-取代空白，Refs使用<space>#分隔符後接#123——這正是源自 git trailer 慣例的格式（:<space>或<space>#）。

規範全文（RFC 2119 關鍵字解釋）

規範本文中使用的關鍵字：MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、RECOMMENDED、MAY、以及 OPTIONAL，均以 RFC 2119 為參考解釋。也就是說，MUST是強制要求、MAY是可選、SHOULD是建議，這決定了某條規則「違反」時的嚴重程度。以下為 1.0.0 規範的 16 條規則全文：

1. 每個提交最前面「必須 MUST」要有類型，類型由名詞組成，例如：feat、fix等，後接上「可選的 OPTIONAL」作用範圍以及「必要的 REQUIRED」一個冒號與空格。
2. 當提交一個新功能到你的應用程式或是函式庫時，「必須 MUST」使用feat類型。
3. 當提交一個臭蟲修正到你的應用程式時，「必須 MUST」使用fix類型。
4. 類型之後「可以 MAY」加上作用範圍。個別作用範圍「必須 MUST」由一個描述程式區段的名詞所組成，並用括號包覆。例如：fix(parser):。
5. 描述「必須 MUST」緊鄰在類型／作用範圍後的冒號與空格。描述是對於程式碼修改的簡短總結，如fix: array parsing issue when multiple spaces were contained in string。
6. 在簡短的描述後「可以 MAY」加上更長的提交正文，提供關於對程式碼變更的額外脈絡資訊。正文「必須 MUST」在描述後的一個空行之後開始。
7. 提交正文為自由格式，並「可以 MAY」有數個以換行字元區分的段落。
8. 在正文後「可以 MAY」有一個或多個頁腳，頁腳在正文後空行之後開始。每個頁腳「必須 MUST」包含一個符記（token），並接著以:<space>或<space>#分隔，再緊鄰一個字串值。（本處靈感係源自於 git trailer convention。）
9. 頁腳的符記「必須 MUST」使用-作為空白字元，如Acked-by（這有助於區分出頁腳與多段落的正文）。但BREAKING CHANGE則為例外，且也「可以 MAY」作為符記使用。
10. 頁腳的值「可以 MAY」包含空白與換行，解析時「必須 MUST」在遇到下一組有效的符記／分隔時停止。
11. 重大變更「必須 MUST」作為提交中的類型／作用範圍的前綴，或是在頁腳中作為一個段落存在。
12. 若放置於頁腳，重大變更「必須 MUST」維持大寫文字BREAKING CHANGE，而後緊鄰一個分號、空白、並接著描述。如：BREAKING CHANGE: environment variables now take precedence over config files。
13. 若作為類型／作用範圍的前綴，重大變更「必須 MUST」以一個!識別，並緊鄰於:之前。若使用!，頁腳段落的BREAKING CHANGE:則「可以 MAY」被省略，且提交說明「應當 SHALL」用來描述重大變更。
14. 除了feat與fix以外的類型「可以 MAY」被用於提交訊息內，如：docs: updated ref docs。
15. 組成慣例式提交資訊的單位在實作時除了大寫的BREAKING CHANGE外，「禁止 MUST NOT」區分大小寫。
16. 在作為頁腳符記時，BREAKING-CHANGE「必須 MUST」與BREAKING CHANGE視為相同的。

規範條文的解析重點

• 第 1 條（前綴結構）：強制的只有「類型 + 冒號 + 空格」三件套，作用範圍與!都是可選的。feat:、fix:都是合法前綴，feat(parser):、feat(api)!:也是。
• 第 5 條（描述）：描述必須緊接在冒號與空格之後，中間不能再插入其他內容，且應是簡短總結——這決定了提交標題（第一行）的可讀性。
• 第 8～10 條（頁腳語法）：這是機器解析最容易出錯的部分。頁腳符記與值之間必須是:<space>或<space>#；符記內部用-取代空白以與多段落正文區分；多個頁腳值解析到「下一個有效符記／分隔」時停止——這保證了多頁腳與跨行值的正確解析。
• 第 11～13 條（重大變更的兩種宣告方式）：前綴式（!）與頁腳式（BREAKING CHANGE:）是等價且可省略其一；第 16 條進一步規定BREAKING-CHANGE（連字號）作為頁腳符記時與BREAKING CHANGE同義，兼顧了不同書寫習慣的工具相容性。
• 第 15 條（大小寫）：除BREAKING CHANGE外，實作者在解析時不得區分大小寫，例如Feat與feat應被同等對待；但BREAKING CHANGE必須大寫（第 12 條）。

從實作角度看，這些規則直接決定了解析器（parser）的行為：例如頁腳符記的-規則、BREAKING-CHANGE同義規則、大小寫不敏感規則，都是 content/next/index.md 中提及的 go-conventionalcommits、commitlint、standard-version 等工具必須遵守的解析細節。

為何要使用慣例式提交

規範原文給出了採用這套慣例的五個直接收益：

• 自動產生修改日誌（Changelog）。
• 基於提交的類型，自動決定語意化版本的升級。
• 向同事、公眾以及其他的利益相關者傳達變化的過程。
• 觸發建置與發布流程。
• 讓大家探索更有結構的提交歷史，使你的專案更容易被貢獻。

第五點尤其關鍵：結構化提交歷史本身就是開源專案的「貢獻門檻降低器」——新貢獻者可以從提交歷史中快速理解專案的演進脈絡，而維護者可以依賴工具自動生成 release notes。

FAQ：常見問題與官方解答

規範 FAQ 部分針對實務中最高頻的問題給出權威解答，以下完整收錄。

在初始的開發階段，我該如何處理提交說明？

我們建議你可以就像是產品已經發行的那樣去執行。因為通常都會有人使用你的軟體，即使是你的軟體開發的同事們，他們會希望知道修正了什麼以及有什麼重大變更等資訊。

提交標題中的類型應該要用大寫還是小寫？

大小寫都可以，但是最好是一致的。（對應規範第 15 條：實作工具不得區分大小寫，但團隊內部保持一致仍是最佳實踐。）

當提交符合一或多種提交類型，我應該怎麼做？

退回並盡可能切成多個提交。慣例式提交的一個好處就是它能夠促使我們做更有組織的提交與拉取請求（PR, Pull Request）。

這不會阻礙快速開發與快速迭代嗎？

它阻礙用非組織化的方式快速前進。它幫助你長期能在橫跨多個專案與多個貢獻者協作時都能快速前進。

慣例式提交會讓開發者受限於提交的類型，因為他們會用已提供的類型去思考嗎？

慣例式提交鼓勵我們多使用某些類型的提交，例如fixes。除此之外，慣例式提交的彈性也允許你的團隊使用自己的類型，以及隨時間推移更改這些類型。

這與 SemVer 有什麼關係呢？

fix類型的提交應該對應到PATCH發行版。feat類型的提交應該對應到MINOR發行版。含有BREAKING CHANGE的提交，無論是什麼類型，都應該要對應到MAJOR發行版。

我對慣例式提交做了擴充（例如：@jameswomack/conventional-commit-spec），我該如何管理這些擴充的版本呢？

我們推薦使用 SemVer 來發行你對這份規範的擴充（並且也鼓勵你做些擴充！）

如果我不小心用錯提交類型，該怎麼辦？

當你使用規範中但是錯誤的類型，例如：將feat寫成fix

在合併或是發行這個錯誤之前，我們推薦使用git rebase -i來編輯提交歷史。而在發行之後，根據你使用的工具與流程，會有不同的清理方式。

當你使用非規範中的類型時，例如：將feat寫成feet

最糟狀況下，即使提交沒有符合慣例式提交的規範，也不會是世界末日。它僅意味著這個提交將會被基於這個規範的工具略過（不會被計入版本號計算與 changelog 生成）。

所有的貢獻者都需要使用慣例式提交的規範嗎？

不用！如果你使用的是基於 squash 的 Git 工作流程，主維護者可以在合併時清理提交說明，因此這不會對一般的提交者產生額外的負擔。有一種常見的工作流程是讓 git 系統自動從 pull request 中 squash 出提交，然後提供一份表單給主維護者，用以在合併的時候輸入合適的 git 提交說明。

慣例式提交要如何處理回退提交（revert commit）？

回退程式碼可能非常複雜：你是回退了多個提交嗎？如果你回退了一個功能，那麼下一個發行版應該要是修正檔嗎？

慣例式提交沒有強制定義回退的行為。反而，我們將這個問題留給工具的作者，靈活運用類型以及頁腳來開發處理回退的邏輯。

其中一個推薦的方法時使用revert類型，並在頁腳中參照到被回退的 SHA 雜湊：

revert: let us never again speak of the noodle incident Refs: 676104e, a215868

這個範例同時示範了「自訂類型（revert）」與「頁腳參照（Refs:+ SHA）」的組合用法——兩者都是規範明確允許的彈性空間。

在官方倉庫中的落地方式

conventionalcommits.org 這個倉庫本身就是這份規範的「活樣本」：它以 HUGO 靜態站生成器維護規範網站，並採用**「一版本一目錄、多語言平行翻譯」**的組織方式。如果你想查看最新草案與版本演進，以下倉庫位置可以直接參考：

• content/v1.0.0/：1.0.0 正式版，收錄英文原文 index.md 與 20+ 種語言翻譯（含本篇主體 index.zh-hant.md 繁體中文版、index.zh-hans.md 簡體中文版）。
• content/next/index.md：規範的下一版草案（draft: true），其中已經出現!!與INITIAL STABLE RELEASE等 1.0.0 尚未收錄的新概念，適合追蹤規範未來的演進方向。
• content/v1.0.0-beta.4/index.md等 beta 目錄：保留了 1.0.0 之前各草稿版本的歷史面貌，可以用來對比!語法、頁腳規則的放寬過程。
• config.yaml：站點的多語言配置。其中zh-hant區塊定義了繁體中文的languageName: 繁體中文、title: 慣例式提交、description（一種用於增加提交說明之人機可讀性意義的規範），以及versions（current: v1.0.0 與歷史版本列表）——這也解釋了規範網站如何同時呈現多個版本。
• README.md：說明倉庫佈局——./content存放規範所有版本，./content/**/index.[lang].md是語言翻譯的存放規則，並提供新增翻譯的流程（用hugo new [version]/index.[lang].md建立文件後，在 config.yaml 中加入對應語言）。
• themes/conventional-commits/layouts/_default/single.html：規範內容的渲染模板，將 Markdown 內容經由{{.Content}}輸出為帶有 markdown-body 樣式的頁面，並搭配 welcome 區塊展示版本徽章。

如果你想在本地預覽這份規範的網站效果，倉庫提供了 docker-compose.yml：在安裝 docker-compose 後執行docker-compose up，編譯完成即可訪問http://localhost:1313查看（詳見 README.md 的「Running project locally」一節）。此外，README 還提供了可直接嵌入自己專案 README 的「Conventional Commits 1.0.0」徽章 Markdown 片段，用於向使用者宣告你的專案遵循此規範。

結語：把規範變成團隊的默認習慣

從本篇文章的完整內容可以看出，慣例式提交 1.0.0 的設計哲學是「少量強制 + 大量彈性」：強制只有類型、冒號與描述這三個要素（規範第 1、5 條），而作用範圍、正文、頁腳、自訂類型、!前綴全部是可選項。正因如此，它既能被 commitlint 等 linter 嚴格校驗，也能被 standard-version、semantic-release 等工具自動推斷版本號，同時又不會束縛團隊自訂類型與工作流程。落地建議很簡單：先在提交模板中固定<type>(<scope>): <description>格式，再逐步引入「!或BREAKING CHANGE:必須標記重大變更」的審查規則，最後接入自動化工具生成 changelog——這份規範會很快成為團隊協作的默認語言。

• 文档