Skip to content
FEE
Frontend Engineering Essentials
Mid Level

發布自動化:語義化版本控制與變更日誌 ​

背景脈絡 ​

發布一個函式庫或應用程式的新版本,過去需要開發者做出幾個手動決策:這是 bug 修復還是新功能?是否有破壞性變更?CHANGELOG 要寫什麼?版本號應該用什麼?這些決策往往缺乏一致性,經常在時間壓力下草草完成,而 CHANGELOG 更是事後補寫的事後諸葛,內容不完整,對需要了解變更內容的使用者毫無幫助。

Conventional Commits 從根本改變了這一切。透過在撰寫 commit 的當下,將語義意圖編碼進 commit 訊息,整個 commit 歷史就變成了機器可讀的資料。工具程式接著可以分析 commit 日誌,並確定性地計算出下一個版本號——不需要任何人為決策。CHANGELOG 從相同的資料自動生成。git tag、GitHub Release 和 npm publish 全都自動跟著 tag 進行。

這不只是為了自動化而自動化。它在整個團隊中強制執行紀律:每一個有意義的變更都被分類,分類結果驅動版本號,而版本號向使用者傳達相容性保證。整合你函式庫的下游團隊可以清楚知道 2.0.0 代表什麼(破壞性變更,需閱讀遷移指南),以及 1.4.2 代表什麼(僅 patch 修復,可安全升級)。版本號成為一份契約,而不是一個猜測。

這個領域由兩個工具主導:semantic-release 用於單一套件儲存庫和應用程式,@changesets/cli 用於 monorepo。本文涵蓋兩者,解釋各自的適用時機,並提供可直接用於生產環境的 workflow 範例。


設計思維 ​

為何 Conventional Commits 能解鎖自動化 ​

像 更新了某個東西 這樣的 commit 訊息,對於在情境中閱讀的人類來說有意義,但對機器而言是不透明的。像 fix(auth): handle expired token in refresh flow 這樣的訊息則包含了結構化資訊:type 是 fix(向後相容的 bug 修復),scope 是 auth,description 是精確的。

semantic-release 分析這些結構化訊息的清單,並套用確定性規則集:任何 type 為 feat 的 commit 觸發 minor 版本升級;任何 type 為 fix 或 perf 的 commit 觸發 patch 升級(注意:refactor 觸發 patch 版本是上方 .releaserc.json 中的自訂規則,非 semantic-release 預設行為);任何帶有 BREAKING CHANGE: footer 或 type 後有 ! 的 commit 觸發 major 升級。自上次發布以來所有 commit 中,適用的最高等級升級決定新版本號。沒有任何歧義,沒有委員會決策,沒有「這應該是 1.5 還是 2.0?」的爭論。commit 訊息在變更當下就已做出決定。

這也正確地分配了責任。撰寫破壞性變更的開發者,正是標記 feat!: 或加入 BREAKING CHANGE: footer 的人。他們擁有最多的上下文。發布工具只是讀取他們的意圖。

為何 changesets 在 monorepo 中優於 semantic-release ​

在一個擁有 @myorg/button、@myorg/input 和 @myorg/theme 套件的 monorepo 中,像 feat(button): add loading state 這樣的單一 commit 影響 @myorg/button,但對 @myorg/input 或 @myorg/theme 沒有任何影響。semantic-release 針對單一發布分支分析整個 commit 日誌——它沒有內建「哪些 commit 影響哪個套件」的概念。若不進行大量客製化,這使得它並不適合 monorepo。

Changesets 以不同的方式解決這個問題。當開發者進行變更時,他們也執行 pnpm changeset 並以互動方式回答:「這影響哪些套件?是 major、minor 還是 patch?CHANGELOG 中應該出現什麼?」答案被寫入 .changeset/ 中的一個小型 markdown 檔案。這個檔案與程式碼變更一起被 commit,並在 pull request 中接受審查。

changeset 檔案的權威性是 commit 訊息本身無法達到的:它是由作者撰寫的,作者明確知道哪些套件受到影響以及影響程度。monorepo 中的單一 commit 可能觸及共用工具程式,並將變更級聯到五個套件——changeset 明確捕捉了這一點,而基於 commit 的分析則需要複雜的依賴圖遍歷才能推斷出來。

當發布時機到來,pnpm changeset version 消耗所有待處理的 changeset 檔案,按最高宣告嚴重性升級每個套件,並用 changeset 檔案中的描述更新每個套件的 CHANGELOG。.changeset/*.md 檔案隨後被刪除。後續的 pnpm changeset publish 發布所有具有新版本的套件。Changesets GitHub Action(changesets/action)在 main 分支上維護一個開放的 PR,顯示待處理的版本升級——即「Version Packages」PR。合併這個 PR 就是發布。

為何 CHANGELOG 重要 ​

你函式庫的使用者——內部團隊、開源使用者——需要評估每次升級:「這樣升級安全嗎?有什麼變更?我需要遷移任何東西嗎?」若沒有 CHANGELOG,他們只能閱讀 git commit 歷史,而那充斥著雜訊且是為進行變更的開發者而寫的,而非為評估升級的消費者而寫。有了生成的 CHANGELOG,每個發布都有一份按類型分組的使用者可見變更精選清單,並附有回到原始 commit 的連結。

自動化 CHANGELOG 生成使這一切無需額外成本。commit 訊息(或 changeset 描述)已經寫好了;工具將它們組裝成格式化文件並 commit 結果。不再有「記得更新 changelog」的步驟,不再有 changelog 偏差,不再有未附說明文件就發布的版本。

為何 publish-on-tag 優於 publish-on-merge ​

在每次合併到 main 時發布,意味著每次功能、修復或重構落地後都會執行發布步驟。這很少是理想的:你可能想在發布前累積幾個變更,你可能正處於尚未準備好對外公開的功能開發中途,或者你可能只是想讓人工審閱待處理的發布後再讓它上線。

git tag 代表明確、刻意的發布意圖。使用 semantic-release 時,版本升級和 tagging 在 commit 分析後自動發生——但仍然只發生一次,在 workflow 中的受控時間點。使用 changesets 時,tagging 發生在「Version Packages」PR 合併的時候——這是一個人為動作,表示「這批變更已準備好發布」。

Publish-on-tag 也建立了穩定的稽核軌跡:每個 npm 版本都對應一個精確的 git tag 和一個精確的 GitHub Release。「npm 套件中包含什麼」與「原始碼中有什麼」之間的關聯是明確的。


最佳實踐 ​

應該(SHOULD)對所有 commit 訊息使用 Conventional Commits 格式。 type(scope): description 結構是自動化版本計算的機器可讀輸入。工具應該(SHOULD)能夠解析每個 commit 的語義意圖——feat、fix 或帶有 BREAKING CHANGE footer——才能確定性地計算下一個版本號,並生成有意義的 CHANGELOG。

應該(SHOULD)自動化版本號升級與 CHANGELOG 生成,而非手動進行。 單一套件儲存庫和應用程式使用 semantic-release;monorepo 或有多個獨立版本套件的函式庫使用 @changesets/cli。這兩種工具都應該(SHOULD)配置為在 CI 中運行,以確保版本控制的一致性與可稽核性。

禁止(MUST NOT)在自動化工具就位後手動編輯 package.json 中的版本欄位或手寫 CHANGELOG 條目。 手動編輯將被工具覆蓋,並造成令人困惑的衝突。自動化工具必須(MUST)是版本和 CHANGELOG 的唯一來源。

必須(MUST)只從 CI 發布套件,絕不從開發者本地機器發布。 CI 發布的套件具有可重現性、可稽核性,且不受開發者環境差異的影響。個人 npm 發布權限必須(MUST)被撤銷,要求所有發布都通過 CI workflow 進行。

必須(MUST)在執行發布工具的 workflow 中設定 fetch-depth: 0。 semantic-release 和 changesets 都需要讀取完整的 git tag 歷史,以確定自上次發布以來有什麼變更。使用預設的淺層 clone(fetch-depth: 1)將導致工具無法看到前次 release tag,從而計算出不正確的版本。

應該(SHOULD)在 release commit 訊息中加入 [skip ci] 標記。 @semantic-release/git 會將一個 commit 推送回預設分支;若沒有 [skip ci],release workflow 將在 release commit 上再次觸發,浪費 CI 時間。每次自動化工具生成 release commit 時都應該(SHOULD)包含此標記。

應該(SHOULD)對所有版本化套件和函式庫優先採用 publish-on-tag 而非 publish-on-merge。 明確的 git tag 代表刻意的發布意圖;在每次合併到 main 時發布,會讓每個 commit 都成為潛在的發布,並消除在發布前批次累積變更的能力。Publish-on-tag 同時建立穩定的稽核軌跡,使每個 npm 版本都對應至精確的 git tag 與 GitHub Release。


視覺化 ​

以下圖表展示了從合併 pull request 到發布 npm 套件和 GitHub Release 的完整 semantic-release 流程。


範例 ​

1. Conventional Commits 格式參考 ​

bash
# Patch 升級——向後相容的 bug 修復
fix(auth): handle expired token in refresh flow

# Minor 升級——新的向後相容功能
feat(table): add column resizing support

# Minor 升級帶 scope——scope 是選擇性的但很有用
feat: support dark mode via CSS custom properties

# Major 升級——以 '!' 表示破壞性變更
feat(api)!: replace callback API with Promise-based interface

# Major 升級——以 footer 表示破壞性變更
feat(router): add nested route support

BREAKING CHANGE: The `routes` config key is renamed to `children`.
Update all route definitions that use `routes:` to use `children:`.

# 不升級版本——維護類 commit
chore: upgrade eslint to v9
docs: update contributing guide
ci: add dependency audit step
test: add coverage for edge cases in tokenizer
refactor(utils): extract date formatting helpers
style: apply prettier formatting to all files

2. semantic-release:設定與 workflow ​

安裝插件:

bash
pnpm add -D semantic-release \
  @semantic-release/commit-analyzer \
  @semantic-release/release-notes-generator \
  @semantic-release/changelog \
  @semantic-release/npm \
  @semantic-release/github \
  @semantic-release/git

透過儲存庫根目錄的 .releaserc.json 進行設定:

json
{
  "branches": ["main"],
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "conventionalcommits",
        "releaseRules": [
          { "type": "feat", "release": "minor" },
          { "type": "fix", "release": "patch" },
          { "type": "perf", "release": "patch" },
          { "type": "refactor", "release": "patch" },
          { "type": "docs", "release": false },
          { "type": "chore", "release": false },
          { "type": "ci", "release": false },
          { "type": "test", "release": false },
          { "breaking": true, "release": "major" }
        ]
      }
    ],
    [
      "@semantic-release/release-notes-generator",
      {
        "preset": "conventionalcommits",
        "presetConfig": {
          "types": [
            { "type": "feat", "section": "Features" },
            { "type": "fix", "section": "Bug Fixes" },
            { "type": "perf", "section": "Performance Improvements" },
            { "type": "refactor", "section": "Refactoring" }
          ]
        }
      }
    ],
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md"
      }
    ],
    "@semantic-release/npm",
    "@semantic-release/github",
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md", "package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

對應的 GitHub Actions workflow:

yaml
# .github/workflows/release.yml

name: Release

on:
  push:
    branches:
      - main

permissions:
  contents: write       # 推送 release commit 和 tag
  issues: write         # 在發布時關閉 issue(透過 @semantic-release/github)
  pull-requests: write  # 對包含在發布中的 PR 留言
  id-token: write       # 用於 npm provenance(選擇性但建議啟用)

jobs:
  release:
    name: Semantic release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # 取得完整歷史——semantic-release 需要讀取自上次 release tag
          # 以來的所有 commit,以確定下一個版本。
          fetch-depth: 0

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm build

      - name: Release
        run: pnpm exec semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

重點說明:

  • fetch-depth: 0 是必要的。若不設定,actions/checkout 只會做淺層 clone,semantic-release 就無法看到用於確定 commit 範圍的前次 release tag。
  • GITHUB_TOKEN 是自動提供的 token。NPM_TOKEN 必須作為儲存庫 secret 新增(在 npmjs.com → Access Tokens → Automation 類型生成)。
  • release commit 訊息範本中的 [skip ci] 防止無限迴圈:@semantic-release/git 推送的 commit 會觸發 push 事件,但 [skip ci] 告訴 GitHub Actions 跳過該次執行。

3. Changesets:monorepo 設定與 workflow ​

在 monorepo 根目錄初始化 Changesets:

bash
pnpm changeset init

這會建立 .changeset/ 目錄和 config.json:

json
// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

當開發者進行影響一個或多個套件的變更時,他們執行互動式提示:

bash
pnpm changeset
? Which packages would you like to include?
  ◉ @myorg/button
  ○ @myorg/input
  ○ @myorg/theme

? Which packages should have a major bump?
  (none)

? Which packages should have a minor bump?
  ◉ @myorg/button

? Please enter a summary for this change:
  Add loading state to Button component

這會建立類似 .changeset/witty-eagles-fly.md 的檔案:

markdown
---
"@myorg/button": minor
---

Add loading state to Button component. Pass `loading={true}` to display a spinner and disable interaction during async operations.

這個檔案與程式碼變更一起被 commit,並在 pull request 中接受審查。描述是為使用者而寫的,不是為實作者。

Changesets GitHub Action——「Version Packages」PR bot:

yaml
# .github/workflows/release.yml

name: Release

on:
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    name: 建立 release PR 或發布
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm build

      - name: 建立 release PR 或發布到 npm
        uses: changesets/action@v1
        with:
          # 當 changeset 檔案存在時:開啟或更新 Version Packages PR
          # 當 Version Packages PR 被合併時:發布所有已變更的套件
          publish: pnpm changeset publish
          version: pnpm changeset version
          title: "chore: version packages"
          commit: "chore: version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

changesets/action bot 維護一個名為「chore: version packages」的單一開放 PR,它會累積所有待處理的 changeset。PR body 顯示每個套件將升級多少版本,以及每個 CHANGELOG 中會出現什麼內容。當這個 PR 被合併後,版本控制已由合併本身完成——PR 分支已執行過 changeset version,產生了升級後的 package.json 和 CHANGELOG 條目。action 接著只執行 pnpm changeset publish,它會:

  1. 將所有在 package.json 中有新版本但尚未發布到 npm 的套件發布出去
  2. 為每個發布的套件建立 git tag(例如 @myorg/button@2.1.0)
  3. 為每個 tag 建立 GitHub Release

4. 從 CI 使用 NODE_AUTH_TOKEN 執行 npm publish ​

當使用帶有 registry-url 的 actions/setup-node 時,action 會建立一個從 NODE_AUTH_TOKEN 環境變數讀取認證 token 的 .npmrc 檔案。這意味著你不需要手動設定 .npmrc——只需設定環境變數:

yaml
- uses: actions/setup-node@v4
  with:
    node-version: 20
    registry-url: 'https://registry.npmjs.org'  # 或私有 registry URL

- name: Publish
  run: npm publish --access public
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

對於私有 registry(GitHub Packages):

yaml
- uses: actions/setup-node@v4
  with:
    node-version: 20
    registry-url: 'https://github.com/features/actions'
    scope: '@myorg'

- name: Publish
  run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

5. GitHub Releases——自動 vs. 手動 ​

使用 semantic-release 時,GitHub Releases 由 @semantic-release/github 插件自動建立。每個 release 都關聯到新的 git tag,並填入生成的發布說明。

使用 changesets 時,GitHub Releases 由 changesets/action bot 在發布時建立。每個套件都會有自己的 GitHub Release,標記為 @myorg/package@x.y.z。

6. 選擇 semantic-release 與 changesets ​

考量標準semantic-releasechangesets
儲存庫類型單一套件Monorepo / 多套件
版本輸入來源commit 訊息類型明確的 changeset 檔案
作者參與程度無(全自動)作者在 PR 時建立 changeset
CHANGELOG 品質良好(來自 commit 訊息)優秀(為使用者而寫)
跨套件協調有限內建支援
最適合應用程式、單一函式庫元件函式庫、設計系統、SDK

常見錯誤 ​

對功能用 fix: 而對任何重要事項用 feat:。 commit type 是版本計算的輸入。無論改變感覺有多重大,feat: 觸發 minor 升級,fix: 觸發 patch 升級。鬆散地使用這些類型——「我叫它 feat: 因為這是個大 PR」——會產生不正確的版本號。向團隊灌輸語義:feat: 表示向使用者公開的新能力;fix: 表示糾正現有行為。

在 commit footer 中忘記 BREAKING CHANGE:。 沒有 BREAKING CHANGE: footer(或 ! 後綴)的破壞性變更,將被分析為常規的 feat: 或 fix:,只觸發 minor 或 patch 升級。major 版本不會遞增,而升級的使用者將遭遇意外的中斷。在合併任何移除或重命名公開 API 的 PR 之前,請驗證 commit 包含了破壞性變更標記。

開啟「Version Packages」PR 後手動發布。 使用 changesets 時,changesets/action bot 處理完整的發布週期。在合併 bot 的 PR 後在本地手動執行 pnpm changeset publish,可能導致重複發布或使用錯誤的認證上下文發布。讓 bot 來做發布。

在 PR review 中忽略 changesets。 隨 PR commit 的 changeset 檔案是變更的一部分——它描述了對使用者可見的影響。審查者應該閱讀它:版本升級合適嗎?CHANGELOG 描述對使用者來說準確且有用嗎?一個將破壞性變更標記為「minor」的 changeset,將導致 minor 版本升級而不是 major 升級。

在 monorepo 中未使用 workspace 插件就使用 semantic-release。semantic-release 原生不理解 pnpm 或 npm workspaces。在沒有專門插件的情況下在 monorepo 中使用它,通常會導致所有套件基於整個 commit 歷史一起版本控制,這違背了獨立套件版本控制的目的。Monorepo 請使用 changesets。


相關 FEE ​


參考資料 ​