用 Brewfile 固定雲端 Mac 的 Homebrew 工具鏈

一台雲端 Mac 連續執行數週建置工作後，最常見的環境問題往往不是缺少工具，而是不同人曾在不同時間安裝工具：某個工作依賴 jq，另一支指令碼假設系統已有 swiftlint，臨時疑難排解時又留下了幾個 formula。新機器接手時，只複製儲存庫並不能還原這一層系統相依性。Brewfile 適合用來回答「需要哪些工具」，但它並不是精確的版本鎖定檔。更可靠的做法，是分別管理需求宣告、版本證據與清理流程。

先盤點機器，不要直接匯出全部內容

先確認 Homebrew 路徑與目前的架構，避免指令碼繼續使用另一套歷史路徑。

command -v brew
brew --prefix
uname -m
brew doctor

接著分別查看頂層 formula、所有版本與背景服務：

brew leaves
brew list --formula --versions
brew services list

brew leaves 比完整清單更適合作為需求宣告的起點，因為它主要顯示主動安裝的頂層工具。完整版本清單則應封存為建置證據，而不是原封不動地塞進 Brewfile。

不要在仍有建置工作執行時升級或清理。請先停止工作分派，再確認沒有編譯器、資料庫或輔助服務正被行程占用。

如果機器已使用一段時間，可以先匯出候選檔案，再逐行審查：

mkdir -p ci/homebrew
brew bundle dump --force --file=ci/homebrew/Brewfile.candidate
git diff -- ci/homebrew/Brewfile.candidate

候選檔案可能包含個人工具、臨時除錯軟體，或與專案無關的圖形介面應用程式。只有建置與疑難排解確實需要的項目，才應納入正式清單。

將 Brewfile 視為需求宣告

面向 iOS 持續建置的基本清單可以維持得很精簡：

brew "git"
brew "jq"
brew "swiftlint"
brew "xcbeautify"

將檔案提交為 ci/homebrew/Brewfile，安裝時明確指定路徑：

brew bundle check --file=ci/homebrew/Brewfile
brew bundle install --file=ci/homebrew/Brewfile --no-upgrade

check 適合放在工作的進入點。它只驗證需求宣告是否已滿足，不應在每次建置工作中自動執行完整升級。install --no-upgrade 可以補齊缺少的工具，同時降低一般建置意外改動既有環境的風險。

依職責拆分清單

如果同一台 VMKeep 雲端 Mac 需要承擔多種類型的工作，建議拆分成基本清單與專案清單。例如，基本層只包含 Git、JSON 處理與記錄工具，專案層再加入程式碼規範或發布輔助工具。安裝順序固定為先安裝基本層，再安裝專案層。

不要以一份持續膨脹的全域 Brewfile 涵蓋所有儲存庫。這會使每次清理都難以判斷影響範圍，也會讓新專案誤以為歷史工具是自身不可或缺的相依項目。

分開記錄版本與執行環境

Brewfile 通常不會將一般 formula 鎖定至精確版本。即使兩台機器具有相同清單，也不能證明它們會產生相同結果。每次環境變更後，都應儲存實際的版本快照：

{
  date -u
  sw_vers
  xcodebuild -version
  brew --version
  brew list --formula --versions
} > ci/homebrew/toolchain.snapshot.txt

版本快照可以作為管線產出，也可以在通過審查的環境升級後提交至維運記錄。發生差異時，應先比較 Xcode、macOS、Homebrew 與直接相依項目的版本，再檢查專案鎖定檔，不要一開始就刪除所有快取。

明確劃定版本邊界

brew pin 只能阻止目前機器上的本機升級，無法保證另一台新機器仍可取得相同的歷史版本。因此，它可以作為短期保護措施，但不能取代固定的機器映像、專案專用版本管理器，或經過驗證的二進位成品。

對於會直接影響產出物的工具，應讓指令碼在啟動時檢查可接受的版本範圍，並在不符合條件時明確失敗。對於只負責美化記錄輸出的工具，則可以允許較寬鬆的範圍，避免非關鍵差異導致建置中斷。

使用預覽與閒置時段安全清理

正式清理前，先查看 Brewfile 未宣告的項目：

brew bundle cleanup --file=ci/homebrew/Brewfile

這一步僅用於審查輸出。確認清單中的 formula 未被其他專案、LaunchAgent 或背景服務依賴後，才執行：

brew bundle cleanup --file=ci/homebrew/Brewfile --force
brew autoremove
brew cleanup

共享機器尤其需要謹慎：某個 formula 不在目前儲存庫的 Brewfile 中，不代表其他工作沒有使用它。更穩妥的界線，是讓一類長期工作負載對應一台專用實體節點；至少也應使用獨立的執行帳號、獨立工作目錄與各自的清單。

清理後重新執行 brew bundle check，再跑一條最小驗收流程：輸出工具版本、解析專案設定，並完成一次不會上傳產出物的建置。只有這三個步驟全部通過，環境變更才算完成。

將環境變更轉化為可審查事件

穩定的流程不應允許建置指令碼隨意執行 brew install。新增工具時，提交內容應同時包含 Brewfile 變更、用途說明、版本快照與復原方式。升級則應安排在獨立的維護時段進行，先驗證具代表性的專案，再恢復工作分派。

建議將日常檢查收斂為四項：

1. brew bundle check 是否通過；
2. Xcode 與關鍵 formula 的版本是否符合預期；
3. Brewfile 是否存在未經審查的變更；
4. 是否有未宣告的背景服務持續執行。

Brewfile 的價值不在於自動裝滿所有工具，而是將系統相依性從「機器上的既成事實」轉化為儲存庫中可討論、可比較、可復原的需求宣告。搭配版本快照與審慎的清理流程，雲端 Mac 的環境問題就能從臨時猜測，轉化為有證據可循的設定差異。

常見問題