Xcode 缓存

Xcode 缓存 {#xcode-cache}

Tuist 支持 Xcode 编译缓存，允许团队通过利用构建系统的缓存功能来共享编译产物。

Xcode 缓存是在 Xcode 26 中引入的。你可能也看到它被称为 Xcode 构建缓存；它重用按输入键控的编译产物，Tuist 的远程缓存使这些产物可以在机器之间共享。

设置 {#setup}

::: warning 要求

一个 Tuist 账户和项目
Xcode 26.0 或更高版本

:::

如果你还没有 Tuist 账户和项目，可以通过运行以下命令创建一个：

tuist init

一旦你有了引用你的 fullHandle 的 Tuist.swift 文件，你可以通过运行以下命令为你的项目设置缓存：

tuist setup cache

此命令创建一个 LaunchAgent，在启动时运行本地缓存服务，供 Swift 构建系统使用以共享编译产物。此命令需要在本地和 CI 环境中各运行一次。

要在 CI 上设置缓存，请确保你已经通过身份验证。

配置 Xcode 构建设置 {#configure-xcode-build-settings}

将以下构建设置添加到你的 Xcode 项目：

COMPILATION_CACHE_ENABLE_CACHING = YES
COMPILATION_CACHE_REMOTE_SERVICE_PATH = $HOME/.local/state/tuist/your_org_your_project.sock
COMPILATION_CACHE_ENABLE_PLUGIN = YES
COMPILATION_CACHE_ENABLE_DIAGNOSTIC_REMARKS = YES

请注意，COMPILATION_CACHE_REMOTE_SERVICE_PATH 和 COMPILATION_CACHE_ENABLE_PLUGIN 需要添加为用户定义的构建设置，因为它们没有直接在 Xcode 的构建设置 UI 中暴露：

::: info 套接字路径

运行 tuist setup cache 时将显示套接字路径。它基于你项目的完整句柄，将斜杠替换为下划线。

:::

你也可以在运行 xcodebuild 时通过添加以下标志来指定这些设置，例如：

xcodebuild build -project YourProject.xcodeproj -scheme YourScheme \
    COMPILATION_CACHE_ENABLE_CACHING=YES \
    COMPILATION_CACHE_REMOTE_SERVICE_PATH=$HOME/.local/state/tuist/your_org_your_project.sock \
    COMPILATION_CACHE_ENABLE_PLUGIN=YES \
    COMPILATION_CACHE_ENABLE_DIAGNOSTIC_REMARKS=YES

::: info 生成的项目

如果你的项目是由 Tuist 生成的，则无需手动设置这些设置。

在这种情况下，你只需要在 Tuist.swift 文件中添加 enableCaching: true：

import ProjectDescription

let tuist = Tuist(
    fullHandle: "your-org/your-project",
    project: .tuist(
        generationOptions: .options(
            enableCaching: true
        )
    )
)

:::

缓存上传策略 {#cache-upload-policy}

默认情况下，缓存服务会将产物下载和上传到远程缓存。你可以使用 Tuist.swift 文件中的 cache 选项来控制此行为，以启用只读模式，在该模式下产物会被下载但永远不会被上传：

import ProjectDescription

let tuist = Tuist(
    fullHandle: "your-org/your-project",
    cache: .cache(
        upload: false
    ),
    project: .tuist(
        generationOptions: .options(
            enableCaching: true
        )
    )
)

一个常见的模式是仅从 CI 上传产物（在那里构建是可重现的），同时保持本地环境为只读。你可以使用 Environment.isCI 实现这一点，它检查大多数 CI 提供商设置的 CI 环境变量：

import ProjectDescription

let tuist = Tuist(
    fullHandle: "your-org/your-project",
    cache: .cache(
        upload: Environment.isCI
    ),
    project: .tuist(
        generationOptions: .options(
            enableCaching: true
        )
    )
)

通过此设置，本地构建可以从缓存的产物中受益而不需要上传，而 CI 构建会为团队的其他成员填充缓存。

持续集成 {#continuous-integration}

要在 CI 环境中启用缓存，你需要运行与本地环境相同的命令：tuist setup cache。

对于身份验证，你可以使用 OIDC 身份验证（推荐给支持的 CI 提供商）或通过 TUIST_TOKEN 环境变量使用账户令牌。

使用 OIDC 身份验证的 GitHub Actions 示例工作流程：

name: Build

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v2
      - run: tuist auth login
      - run: tuist setup cache
      - # 你的构建步骤

有关更多示例，包括基于令牌的身份验证以及其他 CI 平台如 Xcode Cloud、CircleCI、Bitrise 和 Codemagic，请参阅持续集成指南。