# 產生的 Xcode 專案 {#generated-xcode-project-build-insights}

> [!NOTE]
> 自動產生的 Scheme 會自動包含 `tuist inspect build` 後續動作。
>
> 若你不想在產生的 Scheme 中追蹤建置洞察，請使用 [buildInsightsDisabled](https://projectdescription.tuist.dev/documentation/projectdescription/tuist) 停用。

若你使用帶有自訂 Scheme 的產生專案，需自行加入後續動作。適用於 [Mise](https://mise.jdx.dev/)：

```swift
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](https://brew.sh/) 安裝：

```swift
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 中的建置洞察 {#continuous-integration}

若要在 CI 中追蹤建置洞察，請確保 CI 已<.localized_link href="/guides/server/authentication#continuous-integration">通過驗證</.localized_link>。

針對由 Xcodebuild 驅動的 CI，你需要：
- 在叫用 `xcodebuild` 動作時使用 <.localized_link href="/cli/xcodebuild#tuist-xcodebuild">`tuist xcodebuild`</.localized_link>。
- 將 `-resultBundlePath` 加入你的 `xcodebuild` 指令。

若缺少 `-resultBundlePath`，系統不會產生必要的活動記錄與結果套件，`tuist inspect build` 也無法分析該次建置。


## 在私有網路上進行免憑證回報 {#network-trusted-publishing}

自行託管部署可讓開發人員無需登入即可發布已完成的報告。營運人員必須在執行個體上設定 `TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS=true`，並依照 <.localized_link href="/guides/server/self-host/server#network-trusted-access">自行託管指南</.localized_link> 所述重新啟動。此設定適用於所有支援的專案；儀表板中沒有相關設定。請在 scheme 後置動作或終端機使用的環境中，設定自行託管的 URL 與專案。當缺少憑證時，CLI 會自動探索執行個體政策：

```sh
export TUIST_URL="https://tuist.internal.example"
tuist inspect build
# To publish local test results:
tuist inspect test
```

在確實缺少憑證的情況下，活動記錄與 XCResult 套件會在本地解析，並以結構化報告的形式傳送。不會提交原始封存檔、附件、涵蓋率／歷史記錄上傳、遠端處理器、分片參考，或選擇性執行的證據。報告仍可見，但無法更新已認證的測試案例狀態，也無法觸發隔離或失敗自動化流程。儀表板與其他需要權限的命令仍需登入。除非執行個體另行啟用網路信任的快取存取，或已提供憑證，否則請保持快取整合停用。

現有憑證仍維持已認證狀態。無效、損毀、空白或被拒絕更新的憑證會以安全方式失敗並保留在磁碟上，因此後續命令不會在未經簽署的情況下靜默執行。請重新登入，或明確登出作為刻意的復原動作。在升級免憑證用戶端之前，請將所有伺服器複本升級至支援探索功能的版本，並設定最終伺服器 URL，避免重新導向。不支援探索功能的舊版伺服器、已停用的執行個體，以及探索失敗的情況，仍需要驗證。不需要用戶端選擇加入。請獨立設定 `TUIST_ACTOR_ID=""` 以省略設定的參與者聲明；已驗證的憑證身分不受影響。


## 機器指標 {#machine-metrics}

建置洞察可包含在建置期間擷取的機器層級效能指標（CPU、記憶體、網路與磁碟使用量）。要啟用此功能，請設定一個輕量的背景常駐程式，持續採樣系統指標：

```bash
tuist setup insights
```

這會執行一個本機常駐程式，在背景中採樣指標。資料會由 `tuist inspect build` 自動擷取，並隨建置報告一起上傳。

磁碟指標包含讀寫活動，並且在使用相容的 CLI 與伺服器時，也會包含 macOS 系統 Data 磁碟區（`/System/Volumes/Data`）的總容量與可用空間。可用空間不包含可清除空間。「磁碟空間」圖表會顯示已用空間（總容量減去可用空間）以及建置期間的總容量，而不僅是上傳時的數值。它不會測量用於檢出或 DerivedData 的獨立外部磁碟區。

升級 CLI 後，請先執行 `tuist teardown insights`，再執行 `tuist setup insights` 以重新啟動現有的採樣器。採樣必須在建置期間執行；較舊的報告與失敗的測量不會包含磁碟空間數值，也不會顯示為零。磁碟空間採樣遵循現有的 90 天機器指標保留政策。

> [!TIP]
> **CI**
>
> 在建置前於你的 CI 機器上執行 `tuist setup insights`，以便同時擷取該處的機器指標。

若要停止收集機器指標，請執行：

```bash
tuist teardown insights
```

這會卸載常駐程式的 LaunchAgent、移除其 plist 檔案，並從 `~/.local/state` 刪除採樣的指標與常駐程式日誌，確保背景中沒有任何程序繼續執行。


## 回報參與者聲明 {#report-actor-claim}

只有在您將 `TUIST_ACTOR_ID` 明確設為組織範圍的標籤時（例如 `TUIST_ACTOR_ID=employee-123 tuist inspect build`），建立回報的請求才會包含可選的 `x-tuist-actor-id` 標頭。預設不會傳送任何標籤，且 Tuist 不會偵測作業系統的使用者名稱。空的 `TUIST_ACTOR_ID` 會省略所回報的識別碼，但不會移除基於憑證的已驗證身分。識別碼必須是 1–128 位元組的非空格可列印 ASCII 字元；無效的覆寫值會被省略，且不會回退。如果自訂代理伺服器拒絕不熟悉的標頭，請使用空的環境變數覆寫來選擇退出。

已驗證的個人憑證具有優先權；否則，用戶端回報的識別碼會顯示為 **未驗證**，且絕不會授予權限或自動連結至使用者。任何能檢視專案回報的人都能看到這些識別碼，包括專案公開時的公眾檢視者，且它們會包含在資料匯出中，因此請勿包含機密資訊。這適用於建置、測試和命令事件回報。舊版伺服器會忽略此可選標頭，而新版伺服器則接受沒有此標頭的舊版用戶端。沒有識別碼的新共用權杖回報會顯示 **未知**，而非發布組織；歷史回報則保留其先前的歸屬。建置和測試清單會區分已驗證的使用者與未驗證的回報識別碼。除非自行託管的執行個體明確啟用免憑證回報，且用戶端發現該政策，否則仍需要進行驗證。

### Scheme 後續動作 {#actor-claim-post-actions}

參與者聲明預設為停用。若要為 Scheme 後續動作設定聲明，請在該腳本中設定 `TUIST_ACTOR_ID`，而不是依賴 Shell 匯出的變數。從 Dock 啟動的 Xcode 不會繼承 `~/.zshrc` 中的變數。若要使用 Homebrew 明確抑制已設定的聲明，請使用：

```sh
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
export TUIST_ACTOR_ID=""
tuist inspect build
```

使用 Mise 時，請在 Mise 載入其環境後覆寫該值：

```sh
$HOME/.local/bin/mise x -C "$SRCROOT" -- env TUIST_ACTOR_ID="" tuist inspect build
```

請使用明確的標籤而非空值來選擇加入。


## 自訂中繼資料 {#custom-metadata}

你可以透過環境變數將中繼資料附加到建置，以改善篩選效果。

### 環境變數

| 變數 | 格式 | 說明 |
|----------|--------|-------------|
| `TUIST_BUILD_TAGS` | 逗號分隔 | 在單一變數中包含多個標籤。 |
| `TUIST_BUILD_VALUE_*` | 單一值 | 鍵值組，其中後綴為鍵。 |

### 範例

在叫用建置前，於 CI 或你的 Shell 中設定這些值：

```sh
export TUIST_BUILD_TAGS="nightly,ios-team,release-candidate"
```

```sh
export TUIST_BUILD_VALUE_TICKET="PROJ-1234"
export TUIST_BUILD_VALUE_PR_URL="https://github.com/myorg/myrepo/pull/123"
```

