Xcode 建置洞察
處理大型專案時,不應需要重複建置相同的程式碼。Tuist Build Insights 可讓你追蹤建置分析數據,以便在本地與 CI 建置時間成為瓶頸之前識別趨勢。
建置洞察由 tuist inspect build 指令驅動,通常會將其加入至你的 Scheme 的後置動作中。
若要開始追蹤本地建置時間,你可以將 tuist inspect build 指令加入至你的 Scheme 的後置動作中來加以利用:

將「Provide build settings from」欄位設定為可執行檔或你的主要建置目標,以擷取建置組態。
當建置失敗時,不會執行 Scheme 後置動作。
在此情況下,你可以透過在 Scheme 的 .xcscheme 檔案中的 <BuildAction> 元素上,將 runPostActionsOnFailure 設定為 YES 來執行它:
<BuildAction
buildImplicitDependencies="YES"
parallelizeBuildables="YES"
+ runPostActionsOnFailure="YES">
對於 Mise,請在後置動作環境中啟用 tuist:
# -C ensures that Mise loads the configuration from the Mise configuration
# file in the project's root directory.
$HOME/.local/bin/mise x -C $SRCROOT -- tuist inspect build
你的環境的 PATH 不會被 Scheme 後置動作繼承,因此請使用 Mise 的絕對路徑。這取決於你安裝 Mise 的方式。應從目標繼承建置設定,以便 mise 可以從 $SRCROOT 執行。
對於 Homebrew,請將 Homebrew 路徑加入至後置動作環境:
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
tuist inspect build
登入後,系統會追蹤本地建置,並可從 Tuist 儀表板存取:
若要快速存取儀表板,請從 CLI 執行 tuist project show --web。

CI 中的建置洞察#
若要在 CI 中追蹤建置洞察,請確保 CI 已通過驗證。
針對由 Xcodebuild 驅動的 CI,你需要:
- 在叫用
xcodebuild動作時使用tuist xcodebuild。 - 將
-resultBundlePath加入你的xcodebuild指令。
若缺少 -resultBundlePath,系統不會產生必要的活動記錄與結果套件,tuist inspect build 也無法分析該次建置。
在私有網路上進行免憑證回報#
自行託管部署可讓開發人員無需登入即可發布已完成的報告。營運人員必須在執行個體上設定 TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS=true,並依照 自行託管指南 所述重新啟動。此設定適用於所有支援的專案;儀表板中沒有相關設定。請在 scheme 後置動作或終端機使用的環境中,設定自行託管的 URL 與專案。當缺少憑證時,CLI 會自動探索執行個體政策:
export TUIST_URL="https://tuist.internal.example"
tuist inspect build
# To publish local test results:
tuist inspect test
在確實缺少憑證的情況下,活動記錄與 XCResult 套件會在本地解析,並以結構化報告的形式傳送。不會提交原始封存檔、附件、涵蓋率/歷史記錄上傳、遠端處理器、分片參考,或選擇性執行的證據。報告仍可見,但無法更新已認證的測試案例狀態,也無法觸發隔離或失敗自動化流程。儀表板與其他需要權限的命令仍需登入。除非執行個體另行啟用網路信任的快取存取,或已提供憑證,否則請保持快取整合停用。
現有憑證仍維持已認證狀態。無效、損毀、空白或被拒絕更新的憑證會以安全方式失敗並保留在磁碟上,因此後續命令不會在未經簽署的情況下靜默執行。請重新登入,或明確登出作為刻意的復原動作。在升級免憑證用戶端之前,請將所有伺服器複本升級至支援探索功能的版本,並設定最終伺服器 URL,避免重新導向。不支援探索功能的舊版伺服器、已停用的執行個體,以及探索失敗的情況,仍需要驗證。不需要用戶端選擇加入。請獨立設定 TUIST_ACTOR_ID="" 以省略設定的參與者聲明;已驗證的憑證身分不受影響。
機器指標#
建置洞察可包含在建置期間擷取的機器層級效能指標(CPU、記憶體、網路與磁碟使用量)。要啟用此功能,請設定一個輕量的背景常駐程式,持續採樣系統指標:
tuist setup insights
這會執行一個本機常駐程式,在背景中採樣指標。資料會由 tuist inspect build 自動擷取,並隨建置報告一起上傳。
磁碟指標包含讀寫活動,並且在使用相容的 CLI 與伺服器時,也會包含 macOS 系統 Data 磁碟區(/System/Volumes/Data)的總容量與可用空間。可用空間不包含可清除空間。「磁碟空間」圖表會顯示已用空間(總容量減去可用空間)以及建置期間的總容量,而不僅是上傳時的數值。它不會測量用於檢出或 DerivedData 的獨立外部磁碟區。
升級 CLI 後,請先執行 tuist teardown insights,再執行 tuist setup insights 以重新啟動現有的採樣器。採樣必須在建置期間執行;較舊的報告與失敗的測量不會包含磁碟空間數值,也不會顯示為零。磁碟空間採樣遵循現有的 90 天機器指標保留政策。
在建置前於你的 CI 機器上執行 tuist setup insights,以便同時擷取該處的機器指標。
若要停止收集機器指標,請執行:
tuist teardown insights
這會卸載常駐程式的 LaunchAgent、移除其 plist 檔案,並從 ~/.local/state 刪除採樣的指標與常駐程式日誌,確保背景中沒有任何程序繼續執行。
回報參與者聲明#
只有在您將 TUIST_ACTOR_ID 明確設為組織範圍的標籤時(例如 TUIST_ACTOR_ID=employee-123 tuist inspect build),建立回報的請求才會包含可選的 x-tuist-actor-id 標頭。預設不會傳送任何標籤,且 Tuist 不會偵測作業系統的使用者名稱。空的 TUIST_ACTOR_ID 會省略所回報的識別碼,但不會移除基於憑證的已驗證身分。識別碼必須是 1–128 位元組的非空格可列印 ASCII 字元;無效的覆寫值會被省略,且不會回退。如果自訂代理伺服器拒絕不熟悉的標頭,請使用空的環境變數覆寫來選擇退出。
已驗證的個人憑證具有優先權;否則,用戶端回報的識別碼會顯示為 未驗證,且絕不會授予權限或自動連結至使用者。任何能檢視專案回報的人都能看到這些識別碼,包括專案公開時的公眾檢視者,且它們會包含在資料匯出中,因此請勿包含機密資訊。這適用於建置、測試和命令事件回報。舊版伺服器會忽略此可選標頭,而新版伺服器則接受沒有此標頭的舊版用戶端。沒有識別碼的新共用權杖回報會顯示 未知,而非發布組織;歷史回報則保留其先前的歸屬。建置和測試清單會區分已驗證的使用者與未驗證的回報識別碼。除非自行託管的執行個體明確啟用免憑證回報,且用戶端發現該政策,否則仍需要進行驗證。
Scheme 後續動作#
參與者聲明預設為停用。若要為 Scheme 後續動作設定聲明,請在該腳本中設定 TUIST_ACTOR_ID,而不是依賴 Shell 匯出的變數。從 Dock 啟動的 Xcode 不會繼承 ~/.zshrc 中的變數。若要使用 Homebrew 明確抑制已設定的聲明,請使用:
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
export TUIST_ACTOR_ID=""
tuist inspect build
使用 Mise 時,請在 Mise 載入其環境後覆寫該值:
$HOME/.local/bin/mise x -C "$SRCROOT" -- env TUIST_ACTOR_ID="" tuist inspect build
請使用明確的標籤而非空值來選擇加入。
自訂中繼資料#
你可以透過環境變數將中繼資料附加到建置,以改善篩選效果。
環境變數#
| 變數 | 格式 | 說明 |
|---|---|---|
TUIST_BUILD_TAGS |
逗號分隔 | 在單一變數中包含多個標籤。 |
TUIST_BUILD_VALUE_* |
單一值 | 鍵值組,其中後綴為鍵。 |
範例#
在叫用建置前,於 CI 或你的 Shell 中設定這些值:
export TUIST_BUILD_TAGS="nightly,ios-team,release-candidate"
export TUIST_BUILD_VALUE_TICKET="PROJ-1234"
export TUIST_BUILD_VALUE_PR_URL="https://github.com/myorg/myrepo/pull/123"