xcodebuild 找不到符合條件的 Simulator destination，測試還沒真正啟動。
先核對本次 Runner 鏡像與活動 Xcode，再檢查 Runtime、設備清單和 scheme；不要先重裝 Xcode 或改動專案。
適合剛採用 GitHub Actions Xcode 27 Runner、要驗證 iOS Simulator 測試的 CI 工程師。
如果你負責判斷托管 Runner 是否適用，或是否要改用遠端 Mac 執行，也可以依照本文的證據順序排查。
最後更新於 2026 年 10 月 17 日；Runner 可用狀態核對自官方公告，鏡像內容核對自官方 Xcode 27 Runner README。鏡像中的工具與 Runtime 清單會更新，本文不把當次清單視為永久保證。
先辨認失敗發生在哪一層
「找不到 Simulator」不是單一故障。先看工作流程停在哪個步驟：
- 編譯失敗：先查建置錯誤、SDK 或工具鏈，不要直接歸因於 Simulator。
- 目的地比對失敗：
xcodebuild沒有找到符合條件的 destination，測試通常尚未啟動。 - 設備已列出，但測試未完成：問題可能出在 Simulator 啟動、測試執行或測試程式本身，應與 destination 不匹配分開處理。
GitHub Actions 的 Xcode 27 Runner 為何找不到 iOS Simulator？ 常見線索包括工作流程實際使用的鏡像與預期不同、活動 Xcode 指向另一套工具鏈、要求的 iOS Simulator Runtime 未安裝，或 scheme 與 destination 條件不相容。先從該次工作流程記錄確認實際執行環境；只看 workflow 檔案中的標籤，不能證明任務使用了哪一份工具鏈。
GitHub 已公告 Xcode 27 Runner 正式可用，公告列出 xcode-27、xcode-27-xlarge 標籤，並說明該鏡像執行於 macOS 27、使用 Apple Silicon Runner。這些是鏡像類型資訊，不代表每次工作流程的 Runtime 和設備清單都固定相同。官方公告
用錯誤證據對照檢查順序
先記下工作流程使用的 Runner 標籤、鏡像資訊、失敗步驟與錯誤原文。GitHub 說明可從工作流程執行記錄檢查各步驟輸出，應以該次任務記錄為準，而不是根據設定檔推測。查看工作流程執行記錄的方法
| 看到的證據 | 優先檢查 | 不要先做 |
|---|---|---|
xcodebuild 無法配對 destination |
scheme、測試 target、平台與目的地條件 | 改寫整個測試工作流程 |
| Runtime 提示未安裝 | 活動 Xcode 下可用的 Runtime 清單 | 假設 Runner 一定預裝所需系統版本 |
| 設備不在可用清單 | 當次設備清單、設備名稱與系統版本 | 直接猜測設備名稱 |
| 設備存在，但啟動或測試失敗 | Simulator 啟動輸出及測試結果 | 把啟動失敗當成 destination 配對失敗 |
表格中的分類是排查順序，不是對特定鏡像故障的官方判定。Runner 映像會隨維護更新；應對照當下的鏡像 README，不要把某次看到的設備或 Runtime 當成固定配置。
核對 scheme 與 xcodebuild destination
先在同一個 Runner 工作目錄中確認專案使用的 scheme、測試 target 和平台。再用該次任務中的 Xcode 執行 xcodebuild -showdestinations，查看這個 scheme 實際列出的目的地。若使用 workspace，命令要帶入正確的 workspace；使用 project 時則帶入 project。避免只比對顯示名稱，還要確認平台和作業系統版本條件。
xcodebuild 沒有匹配的 destination，先檢查什麼？ 先確認 workflow 傳入的 scheme 是否存在、該 scheme 是否包含預期的測試 target，再比對 destination 指定的平台、設備名稱及系統版本。若可用目的地清單裡沒有符合條件的項目，調整測試請求前先找出缺少的是設備、Runtime，還是 target 本身並非 iOS Simulator 測試。
Apple 的自動化測試文件說明了如何透過 Xcode 命令執行測試與指定測試目的地；用 -showdestinations 查到的結果比猜測設備名稱更適合用來核對當次環境。Apple 自動化測試文件
查明 Runtime 和設備是否真的可用
先確認目前活動 Xcode 下的 Simulator Runtime，再查看可用設備。可以在 Runner 步驟中執行：
xcrun simctl list runtimes
xcrun simctl list devices available
將輸出與測試命令要求的系統版本、設備名稱或 UDID 逐項對照。xcode-27 是 Runner 標籤，不是 Runtime 名稱；使用該標籤不能推定所需的 iOS Simulator Runtime 已安裝。
怎麼確認 xcode-27 Runner 實際安裝了哪個 Simulator Runtime？ 在實際執行任務的 Runner 上，透過活動 Xcode 呼叫 simctl 列出 Runtime 與可用設備，並把輸出保存在工作流程記錄中。之後再對照官方鏡像 README，確認鏡像文件與本次任務是否一致。當次命令輸出才是排查這個任務的直接證據。
若 Runtime 缺少，Apple 提供透過 Xcode 下載及安裝附加元件的官方方法。Apple 附加 Xcode 元件安裝說明 但在托管 Runner 上安裝前，先確認安裝步驟能否在每次任務中可靠執行，以及安裝時間和工作流程成本是否可接受。臨時 Runner 上的環境變更不應被當成後續任務一定保留的設定。
確認活動 Xcode 和實際呼叫路徑
Runner 鏡像標籤與執行中的工具鏈是兩項不同證據。檢查：
xcode-select -p
xcodebuild -version
xcodebuild -showsdks
把輸出與工作流程記錄中的 Xcode 路徑、Runner 標籤及鏡像 README 比對。若 xcode-select 指向的開發目錄不是你預期的版本，先確認 workflow 是否明確選取了正確的 Xcode。若版本正確，但 SDK 或 Runtime 清單仍不符合需求，就不能只靠更換標籤推定問題已解決。
Apple 說明如何設定命令列工具使用的 Xcode；核對時應同時看活動開發目錄與 xcodebuild 實際回報的版本，而不是只看安裝了哪些工具。Apple 命令列工具設定文件
值班時常見的混淆是：設備已出現在清單中，測試卻仍然失敗。這時要保留 xcodebuild 輸出、設備清單與測試結果，確認失敗是在 destination 配對、Simulator 啟動，還是測試執行階段。這是故障分類方式，不代表 Xcode 27 Runner 存在已確認的普遍缺陷。
依當次清單驗證設備名稱與狀態
不要把 workflow 中手動填入的設備名稱當成 Runner 已提供該設備的證據。使用 simctl 列出的當次設備資料，比對 workflow、測試工具及 xcodebuild 命令傳入的名稱、系統版本或 UDID。
若設備存在，但啟動或測試階段才失敗，記錄應包括 Runner 標籤、鏡像資訊、xcode-select -p、xcodebuild -version、Runtime 清單、設備清單和完整測試輸出。這些資料可協助你在相同條件下重跑，並避免把不同層級的問題混在一起。
如何判斷設備名稱錯誤，還是 Simulator 啟動失敗？ 若指定目的地不在 -showdestinations 輸出中，先查名稱、平台和 Runtime；若目的地存在但啟動後才失敗，則保存設備狀態與測試輸出，另外追查啟動及執行錯誤。
用可重現結果決定是否改用遠端 Mac
先以相同提交、相同 scheme 和明確記錄的 Runner 鏡像重跑。分別驗收建置是否完成、Simulator 是否啟動、測試是否得到預期結果。不能只因工作流程變綠就認定測試環境已穩定；也不能把 Simulator 測試當成真實 Apple 設備驗收的替代品。
- [ ] 在該次工作流程記錄中確認實際 Runner 標籤與鏡像資訊。
- [ ] 保存活動 Xcode 路徑、版本及可用 SDK 輸出。
- [ ] 以
simctl記錄當次 Runtime 與可用設備清單。 - [ ] 用正確的 workspace 或 project 檢查 scheme 目的地。
- [ ] 分開記錄建置、Simulator 啟動和測試結果。
- [ ] 用相同提交與設定重跑，確認問題是否可重現。
若托管 Runner 缺少所需 Runtime、工具鏈選擇不易控制，或你需要在可維護的 macOS 環境中重現同一測試，再評估把特定任務移至遠端 Mac。托管 Runner 的便利之處是可直接接入工作流程；但鏡像內容會變動、臨時安裝未必能跨任務保留，而且環境狀態不一定符合長期復現需求。遠端 Mac 則需要你負責環境維護、存取權限和節點驗收，並非所有短期任務都值得搬遷。
如果團隊成員需要從不同地區連線到固定的 macOS 測試節點，可先比較香港 Mac mini 雲端算力方案是否符合實際連線與維運需求。若你要驗證 Apple 平台 CI 節點的遠端執行條件，也可參考 MACCOME 的 Mac 遠端租用方案，再按自己的工具鏈、Runtime 與測試步驟評估是否適用。若只是偶發測試，維持托管 Runner 並把環境證據記錄完整，通常更直接；若需要持續復現且托管鏡像無法滿足條件，再考慮租用 MACCOME 的遠端 Mac，將該項測試獨立執行。