同一個 workflow 的 macOS job 出現不同映像檔版本,甚至只有部分建置失敗?
本週先做兩件事:逐個 job 查看 Set up job 日誌中的 Runner Image Version,再固定提交與工作流程分開重現環境差異和專案錯誤。不要靠重跑直到拿到新版映像檔;若生產建置確實需要更可控的主機,再評估替代方案並以真實 workflow 驗收。
適合閱讀: macOS CI 維護者可用下列步驟整理不同 job 的環境證據。
iOS/macOS 工程師可先判斷失敗是否與 Runner 環境相關,避免未定位原因就修改程式碼。
構建平台負責人可依工具鏈控制、憑據隔離與維護責任,評估是否需要受控 macOS 主機。
最後更新於 2026 年 11 月 2 日;資料核對自 GitHub macOS Runner 官方文件、macOS 26 正式公告、workflow 日誌說明及開放議題 #15208。議題狀態與實際 job 日誌應以你檢查時的資料為準。
GitHub Actions macOS 26 Runner 映像檔過舊:平台報告不等於專案根因
GitHub 在 2026 年 2 月 26 日公告 macOS 26 Runner 已正式可用;官方公告與映像檔發布記錄可用來核對標籤及已發布內容。官方公告不等於每次 job 都會拿到相同映像檔,也不能代替你檢查實際執行紀錄。
另一方面,runner-images 開放議題 #15208於 2026 年 11 月 1 日提出 macOS 26 arm64 jobs 在同一工作流程中可能取得不同映像檔版本的報告。該議題屬待分診的使用者回報,不是 GitHub 已確認的普遍故障,也沒有因此承諾修復方案。個別專案遇到的建置錯誤,同樣不能直接推廣成所有專案都會發生的問題。
因此要分開回答兩個問題:job 實際使用了哪個映像檔?錯誤是否會隨映像檔變化?只看 workflow 宣告的 macOS 標籤,無法證明不同 job 的工具鏈與執行環境完全相同。
怎麼查看 macOS 26 arm64 Runner 的實際映像檔版本?
打開 workflow 的個別 job 執行紀錄,展開 Set up job,依 GitHub workflow 日誌文件查找 Runner 映像檔資訊,記下日誌顯示的 Runner Image Version。不要只截取 workflow 檔案裡的 runs-on 標籤;標籤說明選擇條件,job 日誌才是該次執行的環境證據。
每次都保留成功與失敗 job 的執行紀錄,至少記下提交識別、job 名稱、執行時間、架構、映像檔版本、Xcode 版本及錯誤階段。Xcode 與相關工具版本要從該次日誌或相應官方映像檔說明核對,不要用團隊成員電腦上的版本代替。
注意:Runner Image Version 不同,表示環境可能不同;它本身不能證明映像檔差異造成故障。要把版本差異與錯誤是否同步變化一併記錄。
同一 workflow 的環境差異:標籤相同,不代表 job 完全一致
同一 workflow 裡的 job 即使使用相同標籤,也不應在沒有日誌證據時被視為同一套工具鏈。比較時,把每筆結果按 job、時間和實際映像檔版本排列,再核對作業系統資訊、CPU 架構、Xcode 與專案使用的關鍵工具。
| 比較對象 | 能確認什麼 | 控制度評分(定性) | 主要代價 |
|---|---|---|---|
| GitHub 託管 Runner | 個別 job 日誌中的映像檔與工具鏈資訊;官方發布記錄可作為對照 | 主機管理負擔低;映像檔分配控制度有限 | 每次執行仍須保存日誌並核對實際環境 |
| 自管建置節點 | 由團隊維護的作業系統與工具鏈設定 | 環境控制度較高 | 團隊負責更新、憑據、存取權限及故障處理 |
| 遠端 Mac | 可在團隊管理的 macOS 主機上驗收自有 workflow | 依主機管理方式與操作流程而定 | 需負責工具鏈更新、主機安全與持續維護 |
這是治理責任的定性比較,不是效能測試結果。使用自管節點或遠端 Mac,不代表所有依賴問題都會消失;工具鏈、簽署憑據、快取和建置腳本仍可能造成失敗。若你評估租用主機,可先了解VPSPush 遠端桌面使用方式,再用自己的 workflow 驗證連線、權限與建置流程。
同一個 workflow 為什麼會拿到不同映像檔?
先檢查 job 日誌所列的實際版本與執行時間,再對照官方映像檔發布記錄。工作流程的標籤不應被當成固定映像檔版本;若兩次 job 的 Image Version、架構或工具鏈資訊不同,應先將它們視為不同的測試條件,而不是把差異歸因於程式碼。
為避免把時間差誤認為因果關係,成功與失敗記錄要使用同一提交和相同建置輸入。若版本相同但結果不同,就繼續檢查任務輸入、外部依賴與執行步驟;若版本不同且錯誤也不同,仍須重複驗證,不能只憑一組對照判定映像檔是根因。
舊映像檔與專案故障:固定條件,逐步分流
macOS 26 arm64 Runner 使用舊映像檔後建置失敗,如何定位?
依序處理,避免同時更改程式碼、工具鏈和 workflow,讓結果失去可比性:
第一步:保存原始證據。 保留失敗 job 與相近成功 job 的完整日誌,記錄提交、執行時間、Runner Image Version、架構、Xcode 版本及第一個實際錯誤。不要只抄最末尾的失敗訊息,因為它可能只是上游錯誤的結果。
第二步:建立環境差異表。 逐欄比較兩次 job 的系統資訊、工具版本、環境變數來源與建置輸入。能從日誌確認的才填入;沒有證據的欄位標成未知,不要由標籤或預期值推斷。
第三步:固定程式碼與輸入。 使用同一提交、相同 workflow、相同建置參數及相同依賴鎖定方式重現。若外部套件或下載內容不可固定,就把這項不確定性寫入紀錄,不要把兩次結果當成嚴格等價的測試。
第四步:比較錯誤是否跟著環境變化。 在可比條件下記錄通過與失敗 job。若錯誤只出現在某一映像檔版本,這是關聯線索;仍需排除執行時間、外部依賴或其他工具差異,才可提高對根因的判斷信心。
第五步:單獨驗證專案變更。 如需調整建置腳本或依賴,先只改一項,再用固定條件執行。每次改動都保留對照結果,避免因同時修補多個項目而無法判斷哪個改動有效。
第六步:確認可重現範圍。 用團隊能掌握的環境或節點重跑相同 workflow,對照日誌和產物。若問題仍無法穩定重現,應保留「根因未確認」的結論,而不是將單一使用者議題中的錯誤描述成所有專案的既定故障。
新版已發布與實際 job:發布紀錄不能代替執行驗收
Runner Image Version 更新後,怎樣確認新版已進入實際 job?
把發布時間與 job 執行時間分開記錄。先從官方runner-images 發布記錄確認相關映像檔資訊,再檢查更新後新執行的 job 日誌是否真的顯示相應 Runner Image Version。只有官方發布記錄,不能證明你指定的 job 已使用新版。
若 job 仍顯示舊版本,保留該次記錄並依官方 Runner 選擇說明核對使用的標籤與設定;不要自行假定發布後每個 job 立即切換。重新執行可用於蒐集新紀錄,但依重跑 workflow 與 job 的文件,重跑操作本身不能當成強制分配到新版映像檔的機制。
若你的臨時措施是回退、隔離 job 或重新驗收,先在團隊可控的測試條件下確認效果,再決定是否套用到生產建置。不要假設可以自行排空 GitHub 託管 Runner 的映像檔池。
依環境責任選擇方案:先驗收,再決定是否換主機
以下清單可用來判斷是否已具備評估受控建置主機的條件:
- [ ] 已保存成功與失敗 job 的 Set up job 日誌,並記錄實際 Runner Image Version。
- [ ] 已比較架構、Xcode 與建置使用的關鍵工具版本,而非只看 macOS 標籤。
- [ ] 已用固定提交、workflow 和建置輸入重現,並將「版本相關」與「已證明根因」分開記錄。
- [ ] 已確認團隊能負責主機更新、工具鏈一致性、憑據保護、使用者權限與任務隔離。
- [ ] 已在候選主機上以真實 workflow 驗收建置結果、存取方式與回退流程。
若前幾項尚未完成,先繼續取證,不要急著遷移。若專案要求更可控、可檢查的 macOS 環境,而且團隊有能力維護,才把自管節點或遠端 Mac 納入候選;切換主機不會自動修復依賴錯誤,也不會替你完成簽署憑據和安全政策設定。
當前的 GitHub 託管 Runner 方案,方便直接執行建置,但你不能只依標籤判定 job 使用了哪個映像檔;不同執行的環境需要逐筆核對;重跑也不能保證取得新版。相較之下,獨立 macOS 主機可讓你更直接驗收自訂工具鏈與建置流程,但更新、權限、憑據和維護責任會轉到團隊手上。
如果你反覆遇到主機環境難以核對,先依清單驗收項目測試 VPSPush 遠端 Mac,而不是把它當作託管 Runner 映像檔分配問題的保證性修復。需要短期測試時,可查看VPSPush 方案資訊,再以實際 workflow 決定是否適合租用。
為 macOS 建置工作,選擇可自行管理的實體環境
VPSPush 提供獨享 Mac mini M4 實體機,讓您遠端操作 macOS 桌面,並依專案需求自行設定建置環境。
