# Apple {#bundle-insights-apple}

通过将 `tuist inspect bundle` 指向归档文件、可安装文件或已构建的应用来分析 Apple 应用包：

::: code-group
```bash [Analyze an .ipa]
tuist inspect bundle App.ipa
```
```bash [Analyze an .xcarchive]
tuist inspect bundle App.xcarchive
```
```bash [Analyze an app bundle]
tuist inspect bundle App.app
```
```bash [Analyze by app name]
tuist inspect bundle App --platforms ios --configuration Debug
```
<!-- -->
:::

在 macOS 上，当你传递应用名称而非路径时，Tuist 会从 Xcode 的构建产物中解析已构建的 `.app`（如果设置了 `--derived-data-path` 则会遵循该设置），这与 `tuist share` 的工作方式相同。

该命令会将 bundle 上传到 Tuist，并返回一个详细概览的链接，其中包含内容扫描和模块分解：

![已分析的 bundle](/images/guides/features/bundle-size/analyzed-bundle.png)


## 与 App Store Connect 对比 {#app-store-connect}

Tuist 会精确测量你提供的应用包，且不应用 [App Thinning](https://developer.apple.com/documentation/xcode/reducing-your-app-s-size)。报告的大小对应于 **通用**（未精简）变体——即 App Store Connect 应用文件大小报告中标记为“Universal”的行——而非针对特定设备的变体。

预计数值与 Universal 行处于同一范围，但并不完全相同：

- **安装大小**接近 Universal 安装大小。App Store Connect 报告的数值略高，因为它包含了设备上的开销，例如文件系统块分配和 Apple 自身的估算，而原始文件大小测量无法捕捉这些因素。
- **下载大小**低于 Universal 下载大小。Apple 会在上传后对应用二进制文件进行加密，而加密数据的压缩效率较低，因此 App Store 的压缩下载文件会比 Tuist 测量的 `.ipa` 归档文件更大。这种情况发生在上传后的 Apple 端，因此不会反映在 Tuist 的数值中。

App Store Connect 中针对特定设备的行数值更小，因为 App Thinning 会移除特定设备不需要的 CPU 架构和资源变体。Tuist 目前不提供针对特定设备（精简后）的大小报告。

## 标签 {#tags}

上传包时附加标签，以区分构建变体、环境或发布渠道。包标签遵循与构建洞察标签相同的约定：

```bash
tuist inspect bundle App.ipa --tags paid production
```

在 CI 中，你也可以使用 `TUIST_BUNDLE_TAGS` 设置逗号分隔的标签：

```bash
TUIST_BUNDLE_TAGS="paid,production" tuist inspect bundle App.ipa
```

显式的 `--tags` 会替换环境变量中的标签。标签可以包含字母、数字、连字符和下划线，每个包最多 10 个标签，每个标签最多 50 个字符。同样的选项也适用于 Android 包。`--json` 仅在本地运行，不会上传标签或包。

标签显示在包名称旁边以及包详细信息中。使用仪表板的 **标签** 过滤器并输入标签，以在包列表中包含或排除它。匹配是精确且区分大小写的，即使过滤器操作符标记为 **包含** 和 **不包含**：`paid` 不匹配 `paid-extra`。要从 CLI 进行过滤：

```bash
tuist bundle list --tags paid production
```

CLI、API（`?tags=paid,production`）和 MCP `list_bundles` 工具（`tags: ["paid", "production"]`）返回包含 **所有** 指定标签的包。API 上传接受 `bundle.custom_metadata.tags`；列表和详细信息响应返回 `custom_metadata.tags`。现有不带标签的包仍像以前一样可用。标签用于过滤包列表；它们不会更改大小图表或自动比较和阈值基线。

现有客户端可以继续上传和读取不带标签的包。更新后的客户端也可以读取省略 `custom_metadata` 的旧服务器响应。存储和过滤标签需要支持包标签的服务器版本：旧服务器会忽略上传元数据并拒绝标签过滤器。当未提供标签时，更新后的客户端会省略上传元数据和标签查询参数。

## 了解包大小 {#understanding-sizes}

对于每个分析的包，Tuist 报告两个值：

- **安装大小**：应用安装在设备上后占用的空间。
- **下载大小**：用户下载的压缩大小。对于 Apple 包，仅针对 `.ipa`（归档文件的大小）报告此值；对于 `.xcarchive` 或 `.app` 输入，此值不可用。

大小以字节为单位存储，并使用十进制约定显示，其中 1 MB 为 1,000,000 字节，1 GB 为 1,000,000,000 字节——这与 Apple 报告存储和应用大小的约定相同（参见 [Apple 设备上如何测量存储容量](https://support.apple.com/en-us/102119)）。733,446,863 字节的安装大小显示为 733.4 MB。

## 持续集成 {#continuous-integration}

要跟踪包大小随时间的变化，请在 CI 上分析包。首先，确保你的 CI 已 <.localized_link href="/guides/server/authentication#continuous-integration">通过身份验证</.localized_link>。

Tuist 还需要知道将包报告给哪个项目。如果你尚未连接项目，请运行 `tuist init`，或自行声明句柄：

::: code-group
```swift [Tuist.swift]
let tuist = Tuist(fullHandle: "my-account/my-project")
```
```toml [tuist.toml]
project = "my-account/my-project"
```
<!-- -->
:::

对于没有 Swift 清单的项目（例如 Gradle 项目），请使用 <.localized_link href="/references/tuist-toml">`tuist.toml`</.localized_link>。当两个文件都存在时，`Tuist.swift` 优先。

GitHub Actions 工作流示例：

::: code-group
```yaml [Apple]
name: Build

jobs:
  build:
    steps:
      - # Build your app
      - name: Analyze bundle
        run: tuist inspect bundle App.ipa
        env:
          TUIST_TOKEN: ${{ secrets.TUIST_TOKEN }}
```
```yaml [Android]
name: Build

jobs:
  build:
    steps:
      - # Build your app
      - name: Analyze bundle
        # .aab is recommended over .apk for more accurate size analysis
        run: tuist inspect bundle App.aab
        env:
          TUIST_TOKEN: ${{ secrets.TUIST_TOKEN }}
```
<!-- -->
:::

设置完成后，你可以查看包大小随时间的变化情况：

![包大小图表](/images/guides/features/bundle-size/bundle-size-graph.png)

## 拉取/合并请求评论 {#pullmerge-request-comments}

> [!WARNING]
> **需要 Git 平台集成**
>
> 要获取自动拉取/合并请求评论，请将你的 <.localized_link href="/guides/server/accounts-and-projects">Tuist 项目</.localized_link> 与 Git 平台集成：<.localized_link href="/guides/integrations/gitforge/github">GitHub</.localized_link>、<.localized_link href="/guides/integrations/gitforge/origin">Cursor Origin</.localized_link> 或 <.localized_link href="/guides/integrations/gitforge/entire">Entire</.localized_link>。

一旦你的 Tuist 项目与 GitHub 等 Git 平台（如 [GitHub](https://github.com)）连接，每当你运行 `tuist inspect bundle` 时，Tuist 就会直接在拉取/合并请求中发布评论：

![带有已检查包的 GitHub 应用评论](/images/guides/features/bundle-size/github-app-with-bundles.png)

## 大小阈值 {#size-thresholds}

> [!WARNING]
> **需要 Git 平台集成**
>
> 要使用大小阈值，请将 [Tuist GitHub App](https://github.com/apps/tuist) 连接到你的项目。你可以在项目的集成页面执行此操作。

大小阈值允许你在包大小相对于基线分支增加超过配置的百分比或绝对大小时阻止拉取请求。当违反阈值时，Tuist 会在 PR 提交上创建 GitHub Check Run，阻止合并直到解决大小增加问题：

![显示超出包大小阈值的 PR 状态检查](/images/guides/features/bundle-size/github-pr-check-status.png)

检查运行显示基线大小、当前大小以及配置单位的变化。如果增加是有意为之，你可以直接从 GitHub UI 点击 **接受** 按钮来接受它：

![显示违反阈值的 GitHub 检查运行](/images/guides/features/bundle-size/github-check-run-threshold.png)

### 配置 {#size-thresholds-configuration}

要配置阈值，请转到项目的 **设置 > 包** 选项卡：

![包大小阈值设置](/images/guides/features/bundle-size/bundle-size-thresholds.png)

选择 **安装大小** 或 **下载大小**，然后选择 **阈值类型**：

- **百分比 (%)**：限制相对于基线大小的增长。支持小数百分比，例如 `0.47`。现有的百分比阈值保留其配置的值和行为。
- **绝对大小 (MB)**：限制固定数量的增长，与基线大小无关。输入 `1.5` 以允许最多 1.5 MB 的增长。MB 使用十进制单位：1 MB = 1,000,000 字节。值必须解析为正整数字节数。

![绝对包大小增长阈值配置](/images/guides/features/bundle-size/absolute-size-threshold.png)

两种类型都会与配置的 **基线分支** 上具有相同名称、相同包类型（例如 `.app` 或 `.ipa`）且至少共享一个平台的最新包进行比较，因此模拟器 `.app` 仅与模拟器 `.app` 上传进行比较。可选的 **包名称** 将规则限制为该包。仅当增长 **超过** 限制时检查才会失败；增长相等、大小不变或减小则通过。如果没有匹配的基线或所选指标没有记录的大小，则会跳过该规则。绝对限制支持零大小基线；百分比限制会继续跳过它，因为百分比增长未定义。

### 限制谁可以接受 {#size-thresholds-approvals}

默认情况下，任何对仓库具有写入权限的人都可以接受大小增加，因为 GitHub 会向这些人显示该按钮。要缩小范围，请在 **设置 > 包** 下设置 **谁可以接受**：

- **任何人**：默认值。任何对仓库具有写入权限的人。
- **选定的 GitHub 用户**：仅限你添加的 GitHub 用户名。

不在列表中的人会导致检查失败并附带解释说明，而按钮仍保留给有权使用它的人。

