Xcode Cloud 是 Apple 放在 Xcode 和 App Store Connect 里的构建服务。你配置一个工作流（构建什么、什么时候构建、用哪个版本的 Xcode 和 macOS、构建完做什么），之后每次推送、打开拉取请求、打标签、到了排定的时间，或者有人点 Start Build，Apple 的服务器就会构建、测试和归档你的 App。Apple Developer Program 会员每月含 25 个计算时数；付费方案提供每月 100、250、1,000 或 10,000 小时（价格见下文，2026 年 11 月 1 日读取）。日志和产物最多保存 30 天，所以上架 App Store 的版本要自己下载保存。
开始之前
来自 Apple 的 "Get started" 和配置页面：
- 需要 Xcode 15.0 或更高版本，以及 Apple Developer Program 会员资格。
- 第一次配置必须在 Xcode 里完成（报告导航器 → Cloud 按钮 → Get Started）。第一次构建之后，工作流可以在 Xcode 里改，也可以在 App Store Connect 中该 App 的 Xcode Cloud 标签页里改。
- 能配置工作流的人：账户持有人、管理员、App 管理，或者有创建 App 记录权限的开发者、营销角色。
- 支持的 Git 托管：Bitbucket Cloud 和 Server、GitHub 和 GitHub Enterprise、GitLab 和自建 GitLab。授权访问仓库需要仓库托管方的管理员级权限。
- Apple 提醒：如果你用工具在构建时临时生成或修改项目文件，"Xcode Cloud 的初始配置和之后的构建都可能失败"。项目文件需要原样放在仓库里。
工作流是什么
Apple 的说法是：工作流就是"你希望 Xcode Cloud 执行的步骤的配置"。每个工作流包括：
- General：名称和描述。Apple 建议起好认的名字，比如 "Nightly Builds"，即使你一个人开发也可能有好几个工作流。
- Environment：Xcode 和 macOS 版本、可选的 Clean 构建（不用缓存），以及自定义环境变量。
- 开始条件：什么情况下开始构建。
- 操作：构建、测试、分析、归档。
- 后续操作：通知、TestFlight、上传到 App Store Connect 备审。
Apple 建议的小团队分法：一个工作流在分支或拉取请求有改动时构建并测试；另一个在合并到 main 时构建、测试、分析并归档。
环境里有两点值得知道：
- 构建默认复用缓存的 derived data。要发给 TestFlight 外部测试员的工作流必须打开 Clean，Apple 说这会"明显增加构建所需时间"。
- Apple "可能会更新可用的 macOS 和 Xcode 版本，并要求你更新工作流"。构建机器包含 macOS 和 Xcode 自带的工具，另外装了 Homebrew，方便安装第三方工具。
开始条件
| 开始条件 | 什么时候开始构建 |
|---|---|
| Branch Changes | 任意分支、某个分支、几个分支，或以某个前缀开头的分支有改动 |
| Pull Request Changes | 拉取请求被创建或更新（可按源分支和目标分支过滤） |
| Tag Changes | 标签被创建或更新（任意标签、指定标签，或以 v1 这类前缀开头的标签） |
| On a Schedule for a Branch | 按你选的频率、时间和分支 |
| Manual Start | 团队成员点 Start Build，可限定允许的分支、标签或拉取请求 |
Apple 页面上的细节：
- 新工作流默认是默认分支的 Branch Changes。Apple 指出，对慢的工作流（比如在很多模拟器上跑 UI 测试）来说，这可能太频繁。
- 对拉取请求，Xcode Cloud 会检出源分支和目标分支，在临时环境里合并，再对合并结果执行操作。
- 按文件和文件夹过滤：分支、拉取请求和标签条件可以设为只在某些文件、文件夹或扩展名改动时开始构建，或者对它们跳过构建。同一个条件只能"开始"或"跳过"二选一，文件名里不能用
*之类的通配符。 - 跳过某次推送：在最新推送的那个提交的标题或说明里写
[ci skip]。 - Auto-cancel Builds 默认开启：同一个工作流排进新构建时，正在跑的构建会被取消。可以按开始条件关闭。
- Apple 建议给 TestFlight 构建用排程（比如每周一次），而不是每次改动都发，免得测试员被新版本淹没。
操作
| 操作 | 执行的命令 | Apple 列出的产物 |
|---|---|---|
| Build | 针对某平台和 scheme 执行 xcodebuild build，目标为任意设备或任意模拟器 | 构建产品、构建日志、结果包 |
| Test | 先 xcodebuild build-for-testing，再在你添加的目标设备上 test-without-building | 测试产品和结果包 |
| Analyze | xcodebuild analyze（静态分析） | 构建日志 |
| Archive | xcodebuild archive | 导出的归档或 framework 包、构建日志 |
- 测试操作自己会为测试而构建，不用另加构建操作。目标设备越多，构建越久。
- 测试和分析可以设为 Required to Pass 或 Not Required to Pass。
- 每个操作在各自的临时环境里执行，一个操作产生的文件，另一个操作不一定拿得到。
- 归档操作的 Deployment Preparation 决定签名方式：None（不能用于 TestFlight 或 App Store）、TestFlight (Internal Testing Only)、TestFlight and App Store。发给外部测试员和正式上架都要选最后一个。
后续操作
操作完成后，工作流可以：
- Notify：只在某些构建结果时发邮件、多发给几个人，或者发到 Slack（用 Apple 提供的 Slack App；每个工作流可以用不同频道，也可以发私信；在 App Store Connect 里连接需要 App 管理、管理员或账户持有人角色）。
- TestFlight：把构建版本发给内部或外部测试员。先在 App Store Connect 里建好内部测试员群组。发给外部群组的构建仍要过 TestFlight App 审核，见我们的 TestFlight 清单。
- App Store Connect：上传一个版本，之后可以提交审核。
自定义构建脚本
在 .xcodeproj 或 .xcworkspace 同级目录建一个 ci_scripts 文件夹，把脚本放进去。只认三个文件名，而且必须放在这个文件夹的顶层：
| 文件 | 什么时候运行 |
|---|---|
ci_post_clone.sh | 克隆仓库之后（装工具、改 plist） |
ci_pre_xcodebuild.sh | 执行 xcodebuild 之前 |
ci_post_xcodebuild.sh | 执行 xcodebuild 之后，失败了也会运行（把产物上传到别处） |
每个操作都会跑这些脚本。Apple 的规则：
- 脚本要可执行（
chmod +x），第一行写 shebang，比如#!/bin/sh。否则会以zsh $filename方式运行，可能导致构建失败。 - 不能用
sudo。 - 脚本生成的文件事后会被删除，其他脚本看不到，也不会出现在可下载的产物里。
- 脚本运行时源代码不一定在，所以脚本要用的资源放在
ci_scripts里（或者在里面放符号链接）。 - 出错时返回非零退出码；Apple 的示例用了
set -e。非零退出码会让构建失败。 - 辅助脚本也可以放在
ci_scripts里，Apple 建议它们的文件名不要以ci_开头。
环境变量
自己的变量放在工作流的 Environment 部分。密钥和令牌要勾选 Keep value redacted（Xcode）或 Secret（App Store Connect），这样在日志里显示为 *******。共享环境变量*可以套用到多个工作流、在一处修改，也可以限制只有账户持有人能改。
Apple 列出的始终可用的预定义变量包括：
| 变量 | 值 |
|---|---|
CI、CI_XCODE_CLOUD | 在 Xcode Cloud 中运行时为 TRUE |
CI_BUILD_NUMBER、CI_BUILD_ID、CI_BUILD_URL | 构建号、唯一 ID、App Store Connect 中该构建的链接 |
CI_COMMIT | 正在构建的 Git 提交哈希 |
CI_WORKFLOW、CI_WORKFLOW_ID | 工作流名称和 ID |
CI_START_CONDITION | manual、manual_rebuild、push、pr_open、pr_update 或 schedule |
CI_PRODUCT_PLATFORM | iOS、macOS、tvOS 或 watchOS |
CI_XCODEBUILD_ACTION | analyze、archive、build、build-for-testing 或 test-without-building |
CI_XCODEBUILD_EXIT_CODE | xcodebuild 执行后的退出码 |
CI_PRIMARY_REPOSITORY_PATH、CI_WORKSPACE_PATH | 源代码和工作区的位置，例如 /Volumes/workspace/repository |
CI_BUNDLE_ID、CI_TEAM_ID、CI_XCODE_SCHEME、CI_DERIVED_DATA_PATH | 顾名思义 |
另外一些变量取决于构建是怎么开始的、在跑哪个操作：CI_BRANCH、CI_TAG、CI_GIT_REF；CI_PULL_REQUEST_NUMBER 等 CI_PULL_REQUEST_；测试相关的 CI_RESULT_BUNDLE_PATH、CI_TEST_PLAN 等；归档相关的 CI_ARCHIVE_PATH 和各种 CI__SIGNED_APP_PATH。在测试操作中，Xcode Cloud 会给变量加上 TEST_RUNNER_ 前缀再交给测试进程。构建机器还设置了 HTTP_PROXY 和 HTTPS_PROXY。
计算时数和方案
2026 年 11 月 1 日读取的 Apple Xcode Cloud 页面：
| 方案 | 每月计算时数 | 价格 |
|---|---|---|
| Apple Developer Program 会员自带 | 25 | 已包含 |
| 付费 | 100 | 每月 49.99 美元 |
| 付费 | 250 | 每月 99.99 美元 |
| 付费 | 1,000 | 每月 399.99 美元 |
| 付费 | 10,000 | 每月 3,999.99 美元 |
- 怎么算。 Apple 的定义：一个计算时数是在云端执行具体任务（比如构建 App 或运行测试）所用的一小时，"5 个各 12 分钟的测试等于一个计算时数"。因为操作是并行执行的，一次构建花的时间和报告的用量并不相同。
- 没用完的时数"不会结转到下个月"。
- 谁来购买。 只有账户持有人可以买，在 Apple Developer App 的 Account 标签页里，而且要先配置好工作流。方案以美元计价，部分地区以当地货币计价。
- 升级会开始新的计费周期："配额归零，计算时数按新方案重新给"。降级在本周期结束前仍用当前方案。取消付费方案后，本周期剩余时数还能用，之后回到每月 25 小时。
- 取消付费方案后再退出 Xcode Cloud，你的产品、工作流和构建都将无法访问，且"无法恢复"。
- 查看用量：App Store Connect → 用户和访问 → Xcode Cloud 标签页（团队），或某个 App 的 Xcode Cloud 标签页（单个 App），有趋势图，可导出
.csv；Apple Developer App 的 Account 标签页里也能看。
Apple 的页面没有说明月度时数用完时正在跑的构建会怎样，也没有列出各方案能同时跑几个构建。
日志和产物在哪里
- Xcode：报告导航器 → Cloud 按钮 → 选中一个构建。在报告大纲里展开某个操作，点 Logs；点 Artifacts 可下载构建报告等文件。
- App Store Connect：进入 App → Xcode Cloud 标签页 → Builds，在侧栏展开操作，点 Logs。
- 保存了什么：构建信息、App 二进制、符号信息、测试结果等。
- 保存多久："Xcode Cloud 在构建完成后最多保存产物 30 天。"Apple 建议每个上架的版本都下载并存档产物，因为以后看崩溃报告需要符号信息。
- 删除工作流会把它的构建记录和产物一起删掉。想保留就停用工作流，不要删除。
ci_scripts的输出会出现在构建日志里。
小团队的起步配置
按 Apple 自己的建议：
- 检查：Branch Changes 加 Pull Request Changes，一个测试操作，选一两个模拟器，开着 Auto-cancel，再加文件过滤，改文档不触发构建。
- 测试员：
main分支按排程（每周或每晚），归档选 TestFlight (Internal Testing Only)，TestFlight 后续操作发给内部群组，再用 Notify 发 Slack 或邮件。 - 发布：Tag Changes，标签以
v开头，打开 Clean，归档选 TestFlight and App Store，30 天内下载产物。
第一个月留意用量页面，确认 25 小时够不够，再决定要不要买方案。
常见问题
能只在 App Store Connect 里配置 Xcode Cloud 吗？
不能。Apple 说第一次配置必须在 Xcode 里完成；第一次构建之后，两边都能管理工作流。
Xcode Cloud 会帮我把构建传到 TestFlight 吗？
会，需要归档操作加 TestFlight 后续操作。Apple 原话："Xcode Cloud 会归档构建并替你上传到 App Store Connect。"外部测试员仍需要 TestFlight App 审核，归档要选 TestFlight and App Store。
怎样让某次推送不触发构建？
在最新推送的提交标题或说明里写 [ci skip]。
没用完的计算时数能留到下个月吗？
不能。Apple 说没用完的计算时数"不会结转到下个月"。
产物能下载多久？
构建完成后最多 30 天。
参考资料
均于 2026 年 11 月 1 日读取。
- Xcode Cloud，Apple Developer
- Get started with Xcode Cloud，Apple Developer
- Xcode Cloud，Apple 开发者文档
- Setting up your project to use Xcode Cloud，Apple 开发者文档
- Configuring your first Xcode Cloud workflow，Apple 开发者文档
- Xcode Cloud workflow reference，Apple 开发者文档
- Configuring start conditions，Apple 开发者文档
- Configuring your Xcode Cloud workflow's actions，Apple 开发者文档
- Writing custom build scripts，Apple 开发者文档
- Environment variable reference，Apple 开发者文档
- Sharing environment variables across Xcode Cloud workflows，Apple 开发者文档
- Connecting Xcode Cloud to Slack，Apple 开发者文档
- Distributing your Xcode Cloud builds through TestFlight，Apple 开发者文档
- Developing a workflow strategy for Xcode Cloud，Apple 开发者文档
- Reviewing Xcode Cloud usage data，Apple 开发者文档
Apple 的方案、价格和 Xcode Cloud 设置会变化，具体以上面这些页面的当前内容为准。