# 生成的 Xcode 项目 {#generated-xcode-project-build-insights}

> [!NOTE]
> 自动生成的方案会自动包含 `tuist inspect build` 后置操作。
>
> 如果你不想在生成的方案中跟踪构建洞察，可以使用 [buildInsightsDisabled](https://projectdescription.tuist.dev/documentation/projectdescription/tuist) 禁用它。

如果你在使用带有自定义方案的生成项目，需要自行添加后置操作。对于 [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` 在方案的环境中可用，因为 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>。
- 向你的 `xcodebuild` 命令添加 `-resultBundlePath`。

如果没有 `-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 系统数据卷（`/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"
```

