Xcode 27 的發布說明確認，xctrace record 可用 --show-recording-options 輸出記錄選項 JSON，亦可用 --recording-options 傳入設定檔；Apple 發布說明是這項功能的依據。
症狀：CI 能執行測試，卻沒有可重複檢視的 Instruments 記錄。 最快解法：先固定工作負載，再查詢目標模板支援的選項，接著採集並歸檔 trace。自動採集不等於性能門禁；回歸判定仍須依靠受控測試與獨立分析。
適合需要自動記錄固定應用操作的 iOS／macOS 開發者、維護遠端 Mac 流水線的 CI 工程師，以及要規劃性能任務驗收方式的研發平台維護者。若你只想替一次手動分析找操作說明，這份 CI 流程未必適用。
先固定基線，避免把採集當成測試結論
先選一項可以重複執行的應用操作或測試任務，例如指定畫面載入、特定資料匯入，或一段已存在的自動化測試。接著說清楚你要觀察什麼問題，再選擇相應的 Instruments 模板。這能避免只因為產生了 trace，就推論應用變快或變慢。
流水線中要分清三件事：建置產物、執行中的工作負載、Instruments 記錄。建置成功不代表工作負載已按預期執行；記錄完成也不代表採集期間沒有受到其他程序影響。每次比較時，保留相同程式碼提交、輸入資料與目標環境的識別資訊。
要建立可複查的遠端 Mac 性能分析流程，先記下目前可控的條件：目標應用或裝置、啟動方式、測試輸入、停止條件，以及採集失敗時的處理方式。哪些條件需要固定，由你的測試設計決定；不要用不相關工作負載的數值替專案訂門檻。
接入前核對遠端 Mac 的工具鏈與目標
在流水線實際執行的遠端 Mac 上，確認目前使用的 Xcode 與活動開發者目錄，再確認呼叫到的是該 Xcode 隨附的 xctrace。Apple 的命令列工具參考說明，xctrace 用於記錄、匯入、匯出與符號化 Instruments trace；這不代表每種模板、目標或 CI 工作階段都能無條件使用。
可先從工具解析結果開始檢查：
xcode-select -p
xcrun --find xctrace
xcodebuild -version若指令找不到預期工具，先核對活動開發者目錄與安裝狀態。Apple 的命令列工具安裝說明及工具選擇設定說明可協助你確認應用的是哪一套工具。僅安裝命令列工具套件，不應被當作已確認 Xcode 工具鏈可供這項採集工作使用。
開始記錄前，還要在同一執行環境驗證專案可建置、目標程序或裝置可存取，並確認自動化任務確實能啟動及停止。若這些前置條件未通過，先修正環境，不要把空白或缺漏的 trace 當成性能結果。
查詢模板選項，再準備記錄設定
Xcode 27 的做法不是猜一份通用 JSON，而是先讓目標模板列出可用的記錄選項，再按輸出內容準備設定檔。發布說明列出的 --show-recording-options 與 --recording-options 支援這項流程；它們不保證不同模板會接受相同欄位或設定值。Apple Xcode 27 發布說明
以下命令只展示查詢方向，模板名稱須換成你實際要用的名稱，並依該工具鏈的說明確認參數位置：
xcrun xctrace record --template '<模板名稱>' --show-recording-options把輸出留作流水線設定的依據，避免手寫未經查證的欄位。若模板或 Xcode 更新，重新查詢並檢視差異；不要因舊設定檔仍存在，就推定新環境支援相同選項。這是把 Instruments 記錄選項接入 CI 時最重要的相容性檢查。
在固定工作負載中執行採集
將已確認的模板、記錄設定、目標應用與輸出位置接入流水線。命令中的項目、程序名稱、裝置識別資訊及路徑應使用你自己的值；實際參數以當前 Xcode 的 xctrace 說明和模板查詢結果為準。不要把示意命令中的佔位文字直接當成可執行設定。
執行步驟要能留下清楚的失敗訊號：記錄應用是否成功啟動、工作負載是否完成、停止記錄是否成功，以及程序結束狀態與輸出檔案是否符合預期。若任何一項失敗，讓流水線明確標示採集失敗，而不是只因輸出路徑出現檔案就判定通過。
Apple 的 xctrace 自動化示範可作為命令列自動化的參考；但你仍要在自己的目標與工作階段驗證啟動、記錄和停止流程。將工作負載本身的輸出與 trace 分別留存，才容易分辨測試失敗、採集失敗與性能變化。
依用途選擇採集策略，並為方案評分
下表的評分是流程選擇建議，不是性能實測。若你需要自動留存記錄，才把持續採集納入候選；若目標是判斷回歸，必須另行建立重複測試與分析流程。
| 方案 | 適用情況 | 流程評分 |
|---|---|---|
| 持續記錄並歸檔 | 工作負載穩定、產物追蹤有明確用途 | 推薦：先以隔離任務驗收 |
| 需要時手動觸發 | 採集成本或分析需求尚未釐清 | 有條件：適合先收集流程證據 |
| 直接以 trace 生成結果判定門禁 | 尚無可重複基線或判讀規則 | 不建議：檔案存在不能證明回歸 |
將 trace 歸檔，並確認產物真的可分析
把 trace 作為可追蹤的流水線產物保存，並附上程式碼提交、Xcode 版本、目標識別與工作負載名稱。設定保留方式時，也要確保下游人員能找到相對應的測試輸出；只保留 trace 卻無法追溯它來自哪次執行，會削弱比較價值。
驗收不止是檔案存在。你要實際開啟 trace，或使用適合的匯出方式檢查內容是否可讀、符號資訊是否足以分析。Apple 的呼叫樹檢視與執行比較說明介紹了 Instruments 中檢視與比較 CPU 剖析資料的方式；能否套用到你的記錄，仍取決於模板與採集內容。
常見問題
命令列工具不可用時，如何確認活動開發目錄？
先在流水線的執行身分下查詢活動開發者目錄，再核對 xcrun 找到的工具路徑與預期 Xcode。若指向不符，依 Apple 的命令列工具設定文件修正選擇，然後重跑建置與目標存取檢查；不要只因本機終端可用，就假設 CI 工作階段也選中了相同工具鏈。
在隔離試跑後決定是否納入常規 CI
先在隔離任務中驗收設定查詢、工作負載執行、失敗處理、產物保存與後續分析，再選擇定期執行、需要時觸發，或暫不納入門禁。每次比較性能結果，都要能重現工作負載與執行條件；如果環境、輸入或測試步驟無法追溯，先修好比較流程，而不是急著增加門檻。
最後更新於 2026 年 10 月 30 日；功能依據核對自 Apple Xcode 27 發布說明、命令列工具參考及 Instruments 自動化示範。 若後續 Xcode 27.x 發布說明改變參數或支援範圍，應在目標環境重新查詢選項並驗收。
如果現行方案是用 Linux 主機承擔 Apple 工具鏈工作，你會遇到缺少原生 macOS 開發環境的限制；若依賴開發者本機，執行時段與工具狀態較難統一；自行維護專用 Mac，則要承擔設備採購與持續維護。對需要階段性使用遠端 Mac 的團隊，MACGPU 租用方案可讓你在實際工作負載上驗證 xctrace 採集與產物交付，不必先購置一台專用主機。你可以先了解遠端 Mac 服務與Mac 配置選項；若需求是長期、穩定的高負載，或必須連接實體硬體，則應先比較自購主機與租用方案是否符合維運要求。