產生的 Xcode 專案
自動產生的 Scheme 會自動包含 tuist inspect build 後續動作。
若你不想在產生的 Scheme 中追蹤建置洞察,請使用 buildInsightsDisabled 停用。
若你使用帶有自訂 Scheme 的產生專案,需自行加入後續動作。適用於 Mise:
let project = Project(
name: "MyProject",
targets: [
// Your targets
],
schemes: [
.scheme(
name: "MyApp",
shared: true,
buildAction: .buildAction(
targets: ["MyApp"],
postActions: [
.executionAction(
title: "Inspect Build",
scriptText: """
$HOME/.local/bin/mise x -C $SRCROOT -- tuist inspect build
""",
target: "MyApp"
)
],
runPostActionsOnFailure: true
),
runAction: .runAction(configuration: "Debug")
)
]
)
若你未使用 Mise,需確保 tuist 可在 Scheme 的環境中使用,因為 Xcode 的後續動作不會繼承你 Shell 的 PATH。針對 Homebrew 安裝:
buildAction: .buildAction(
targets: ["MyApp"],
postActions: [
.executionAction(
title: "Inspect Build",
scriptText: """
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
tuist inspect build
""",
target: "MyApp"
)
],
runPostActionsOnFailure: true
)
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"