Xcode 构建洞察

在大型项目中工作不应反复重新构建相同的代码。Tuist Build Insights 让你能够跟踪构建分析数据，从而在本地和 CI 构建时间成为瓶颈之前识别趋势。

构建洞察由 tuist inspect build 命令驱动，该命令通常添加到 scheme 的 post-action 中。

要开始跟踪本地构建时间，你可以将 tuist inspect build 命令添加到 scheme 的 post-action 中：

用于检查构建的 Post-action

Note

将“Provide build settings from”字段设置为可执行文件或你的主构建目标，以捕获构建配置。

Note

当构建失败时，不会执行 post-scheme action。

在这种情况下，你可以通过在相关的 project.pbxprojBuildAction 中将 runPostActionsOnFailure 设置为 YES 来执行它：
diff
<BuildAction buildImplicitDependencies="YES" parallelizeBuildables="YES" + runPostActionsOnFailure="YES">

对于 Mise，在 post-action 环境中激活 tuist：

bash

# -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

Mise 路径解析

你的环境中的 PATH 不会被 scheme 的 post action 继承，因此请使用 Mise 的绝对路径。这取决于你安装 Mise 的方式。应从目标继承构建设置，以便 mise 可以从 $SRCROOT 运行。

对于 Homebrew，将 Homebrew 路径添加到 post-action 环境中：

bash

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

Actor 声明默认处于禁用状态。要为 scheme 的 post-action 配置一个声明，请在该脚本中设置 TUIST_ACTOR_ID，而不是依赖 shell 导出。从 Dock 启动的 Xcode 不会继承来自 ~/.zshrc 的变量。要使用 Homebrew 显式抑制已配置的声明，请使用：

bash

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

使用 Mise 时，在 Mise 加载其环境后覆盖该值：

bash

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

使用显式标签而非空值来选择加入。

登录后，本地构建会被跟踪并可在 Tuist 仪表板中查看：

Tip

要快速访问仪表板，请从 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 post-action 或终端使用的环境中配置自托管 URL 和项目。当缺少凭据时，CLI 会自动发现实例策略：

bash

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

在真正缺少凭据的情况下，活动日志和 XCResult 包会在本地解析并作为结构化报告发送。不会提交原始归档、附件、覆盖率/历史记录上传、远程处理器、分片引用或选择性执行证据。报告仍然可见，但无法更新经过身份验证的测试用例状态或驱动隔离/失败自动化。仪表板和其他特权命令仍然需要登录。除非实例单独启用了网络信任的缓存访问或提供了凭据，否则请保持缓存集成禁用。

现有凭据保持已认证状态。无效、损坏、空白或被拒绝刷新的凭据会以安全方式失败并保留在磁盘上，因此后续命令不会静默变为未签名状态。再次登录或显式注销作为有意的恢复操作。在升级无凭据客户端之前，将每个服务器副本升级到支持发现的版本，并配置最终服务器 URL 而不使用重定向。不支持发现的旧服务器、禁用的实例以及发现失败仍然需要身份验证。不需要客户端选择加入。独立设置 TUIST_ACTOR_ID="" 以省略已配置的 actor 声明；基于凭据的已验证身份不受影响。

机器指标#

构建洞察可以包括在构建期间捕获的机器级性能指标（CPU、内存、网络和磁盘使用情况）。要启用此功能，请设置一个轻量级后台守护进程，持续采样系统指标：

bash

tuist setup insights

这会运行一个在后台采样指标的本地守护进程。数据由 tuist inspect build 自动获取并与构建报告一起上传。

在构建之前在 CI 机器上运行 tuist setup insights，以便在那里也捕获机器指标。

要停止收集机器指标，请运行：

bash

tuist teardown insights

这会卸载守护进程的 LaunchAgent，删除其 plist，并从 ~/.local/state 中删除采样的指标和守护进程日志，因此后台不会留下任何正在运行的内容。

报告 actor 声明#

仅当你将 TUIST_ACTOR_ID 显式设置为组织范围的标签（例如 TUIST_ACTOR_ID=employee-123 tuist inspect build）时，创建报告的请求才会包含可选的 x-tuist-actor-id 标头。默认情况下不发送任何标签，且 Tuist 不会检测操作系统用户名。空的 TUIST_ACTOR_ID 会省略报告的标识符，但不会移除基于凭据的已验证身份。标识符必须是 1–128 字节的非空格可打印 ASCII 字符；无效的覆盖会被省略且不回退。如果自定义代理拒绝不熟悉的标头，请使用空的环境覆盖来选择退出。

已验证的个人凭据优先；否则，客户端报告的标识符显示为未验证，且永远不会授予权限或自动链接到用户。任何可以查看项目报告的人都可以看到标识符，包括项目公开时的公众查看者，并且它们包含在数据导出中，因此请勿包含机密信息。这适用于构建、测试和命令事件报告。旧服务器忽略可选标头，新服务器接受不带该标头的旧客户端。没有标识符的新共享令牌报告显示未知，而不是发布组织；历史报告保留其先前的归属。构建和测试列表区分已验证用户和未验证的报告标识符。除非自托管实例显式启用无凭据报告且客户端发现该策略，否则仍然需要身份验证。

自定义元数据#

你可以通过环境变量为构建附加元数据，以改进过滤。

环境变量#

变量	格式	描述
`TUIST_BUILD_TAGS`	逗号分隔	在一个变量中包含多个标签。
`TUIST_BUILD_VALUE_*`	单个值	键值对，其中后缀是键。

示例#

在调用构建之前，在 CI 或你的 shell 中设置这些值：

bash

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

bash

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