Swift 6.4 SwiftPM SBOM 如何接入 macOS CI？2026

症狀：CI 已完成 Swift 建置，卻沒有能對應該次依賴解析結果的 SBOM。
最快解法：先確認清單要描述套件、產品還是實際建置，再評估在建置命令中產生 SPDX 或 CycloneDX，並將清單與建置產物一起歸檔。

這篇適合維護 Swift Package、iOS 或 macOS 專案的開發者，以及負責 Apple 平台 CI、發布或依賴稽核的人員。
若只需要套件依賴圖，獨立生成命令可能更合適；若要描述建置所使用的依賴，應優先檢視建置命令的 SBOM 路徑。

最後更新於 2026 年 10 月 26 日；Swift 版本資訊核對自 Swift 6.4 發布說明與 Swift 6.4.1 發布公告，命令與範圍則參照 SE-0509 及 SwiftPM 文件。

先選清單範圍，再決定生成方式

SBOM 是軟體組成清單，不是漏洞掃描結果，也不能單獨證明授權合規或符合特定稽核要求。Swift 官方於 2026 年 9 月 15 日發布的 Swift 6.4 納入 SwiftPM SBOM 生成功能，支援 SPDX 與 CycloneDX；Swift 6.4.1 的發布日期為 2026 年 10 月 13 日。日期與功能依據分別見 Swift 6.4 發布說明及修正版發布公告。

先把需求分成三種，避免產出格式正確、範圍卻不符合交付目的的清單：

整個套件的依賴：適合發布套件層級的依賴資訊，或供消費者了解套件宣告的依賴。
某個產品的依賴：適合只交付特定產品、且稽核範圍不應涵蓋其他產品的情況。
一次實際建置的依賴：適合要將清單與特定 CI 建置關聯的情況；優先評估由建置命令生成，並保存該次解析資料與任務識別資訊。

這個區分很重要：SE-0509 說明建置命令產生的 SBOM 可採用 SwiftBuild 建置依賴圖；獨立的 swift package generate-sbom 子命令則採用套件依賴圖。兩者不是同一種範圍，不能只看輸出檔名或格式就認定清單涵蓋了實際建置內容。詳細定義參照官方 SE-0509 提案與SwiftBuild 命令文件。

注意：SBOM 中列出套件，不等於已判斷套件是否有漏洞、是否符合授權條件，或是否滿足組織的交付規範。這些判斷需要另行比對掃描結果、授權政策與稽核要求。

接入前，讓工具鏈與建置狀態可追溯

在 macOS CI 上生成 SBOM 前，先確定流水線使用的是預期 Swift 工具鏈，而且產生清單的工作目錄就是建置專案所在目錄。工具鏈安裝及版本選擇應依 Swift 官方 macOS 安裝說明核對；不要只因節點名稱或映像標籤相同，就假定實際執行的 Swift 版本一致。

接著檢查專案是否能在該工作目錄中重現依賴解析。SwiftPM 會依套件宣告與解析狀態處理依賴，因此建置流程應保存與該次建置相配的解析檔案、版本控制提交識別及 CI 任務識別。SwiftPM 套件描述與依賴宣告方式可查閱官方 PackageDescription 文件。

若同一個儲存庫包含多個套件或多個產品，先確認執行命令時的套件根目錄及選取目標。否則，即使生成成功，清單也可能對應到不同套件根目錄或更廣的範圍，後續很難說明它與交付物之間的關係。

生成命令和建置時產生，如何選擇？

Swift 6.4 SwiftPM SBOM 生成可透過建置流程或獨立命令完成。選擇時要看要描述的是建置依賴圖，還是套件依賴圖，而不是只看哪一條命令比較短。

方式	適用目的	核對重點
在 `swift build` 建置流程中產生	將 SBOM 與一次實際建置連結	依 SE-0509 檢查建置依賴圖範圍、格式及輸出參數
執行 `swift package generate-sbom`	取得套件依賴圖的清單	確認套件根目錄、清單範圍及輸出位置

正式使用前，應在目標工具鏈中執行 swift build --help 與 swift package generate-sbom --help，按目前版本顯示的說明填入格式、輸出位置等選項。本文不預設各版本的選項拼法；SE-0509 與目前 SwiftPM 文件才是核實命令及標誌組合的依據。這樣可避免複製舊版參數後，誤以為命令已按預期生成清單。

SPDX 與 CycloneDX 都是可選輸出格式，應按接收端要求選擇，而不是假設其中一種必然符合所有稽核流程。格式規範可分別參照 SPDX 官方規格列表與 CycloneDX 官方規格說明；交付前還要確認下游工具或接收方支援所選格式。

把生成步驟放進 macOS CI 時間線

以下流程從確認工具鏈一路走到歸檔。可以先在非正式發布工作中驗證，再依專案發布規則決定是否將失敗設為阻斷條件。

第一步：固定本次建置的識別資料

在執行建置前，記錄 Swift 工具鏈版本、程式碼提交識別、工作目錄，以及套件依賴解析檔案。讓建置紀錄與 SBOM 使用相同的任務識別，日後才能確認清單對應哪次建置，而不是只保存一份無法追溯來源的檔案。

第二步：依範圍選擇命令

需要描述建置依賴時，先測試建置命令中的 SBOM 選項；只需要套件依賴圖時，測試獨立的 swift package generate-sbom。依實際需求選擇 SPDX 或 CycloneDX，再依目標 SwiftPM 的 --help 輸出確認格式參數與輸出路徑。

第三步：讓生成步驟依附於建置工作

在 CI 中安排相應的 SBOM 生成命令，並確保它使用與建置相同的工作目錄及依賴解析狀態。若流水線分開執行建置與清單生成，須避免中途重新解析依賴，否則清單可能描述的是另一份解析結果。

第四步：明確處理錯誤與輸出檔案

不要只以「有檔案」判定生成成功，也不要用忽略錯誤的包裝方式掩蓋命令失敗。依 SE-0509 核對所用路徑的錯誤處理行為，並在 CI 中保存命令退出狀態與錯誤紀錄。對正式發布是否阻斷，則由發布政策決定：若 SBOM 是交付必要文件，生成或驗證失敗就應依政策阻止該次交付。

第五步：把清單與建置產物一起留存

將 SBOM 輸出位置加入 CI 的歸檔設定，並讓清單與對應建置產物共享任務識別。可把輸出格式、來源提交、工具鏈與解析檔案一併納入建置紀錄。若團隊還在規劃 macOS 建置節點，可先參考 NowMini 的 macOS CI 相關指南，並依實際工作方式了解遠端 Mac 連線方式。

提醒：生成和歸檔是兩個不同步驟。若 CI 僅在工作目錄中輸出 SBOM，卻沒有把它加入產物保存設定，工作結束後清單仍可能無法供發布或稽核使用。

首次執行後核對依賴範圍與交付物

生成後先確認檔案可以由預定工具讀取，並驗證其中的格式、套件或產品識別及依賴條目。然後將條目與本次依賴解析結果及建置日誌對照；若清單用途是描述實際建置，不要以獨立套件依賴圖生成的結果代替。

條件依賴是容易誤判的邊界。依賴可能受平台、建置條件或產品選擇影響；包圖與建置圖的範圍不同，條目數目不一定相同。應依目標 macOS 建置條件檢查清單是否符合預期，不要把某個環境下未出現的條目直接解讀成套件永遠不會使用該依賴。

驗收項目	通過條件	未通過時的處理
格式	與發布或接收端要求一致，且可由指定工具讀取	依對方支援的 SPDX 或 CycloneDX 格式重新生成
範圍	清楚標示對應套件、產品或建置依賴圖	回查命令選擇、工作目錄與目標產品
可追溯性	能連回工具鏈、依賴解析狀態及 CI 任務	補存建置識別及解析資料，再重新歸檔
產物留存	SBOM 與對應建置產物可一併取得	將輸出路徑納入 CI 歸檔設定後重跑

正式接入前，可逐項勾選以下驗收清單：

[ ] 確認 CI 實際執行的 Swift 工具鏈符合專案預期。
[ ] 確認命令在正確的套件根目錄及建置工作目錄執行。
[ ] 按需求選擇建置依賴圖或套件依賴圖。
[ ] 依目標工具鏈的說明核實命令選項、格式及輸出路徑。
[ ] 對照解析資料與 SBOM 條目，檢查平台或條件依賴差異。
[ ] 確認生成錯誤會留下可追查紀錄，並按發布政策決定是否阻斷。
[ ] 確認 SBOM 已與該次建置產物一同歸檔。

SBOM 不會自動證明沒有漏洞、授權合規或符合特定審計要求。完成清單驗收後，仍須依專案規範執行漏洞檢查、授權審查及所需的交付驗證。

如果團隊目前用 Linux 節點跑不需要 Apple 工具鏈的工作，沒有必要為所有任務改成 Mac；但當流水線必須執行 Xcode 或驗證 Apple 平台建置時，Linux 節點無法直接取代 macOS 環境。自購 Mac mini 適合長期、固定負載且需要自行管理硬體的團隊；若只需臨時測試或階段性 CI，購置設備則會帶來前期支出、閒置與維護負擔。此時可依所需 Swift 工具鏈及持續建置方式評估遠端 Mac；透過 NowMini 了解遠端 Mac 方案，再決定是否租用測試環境，而不必把一次 SBOM 驗收誤當成購置硬體的充分理由。