在 Windows 发起，
交付 IPA 与 dSYM。

iOS 原生 C++ 的编译、链接仍在 Mac。 Windows 路线的价值是把开发、资源处理和构建调度留在 Windows，由 Mac 提供 Apple 工具链能力。Windows 不会把 Visual C++ 编译出的 Win64 程序转换成 iOS 程序。[1][3]

两条路线的工作分工

Windows UAT 在 5.6.1 源码中默认选择 Legacy；Mac 的 Modern/Legacy 由配置与参数决定。不能把 Mac 上“Archive 后导出 IPA”的操作，直接写成 Windows Package Project 的固定后续步骤。 本指南显式传递 Legacy 参数，固定打包主机和远程编译端的路线。[3][4][5][6]

这条路线中，Mac 在原生构建阶段完成链接，生成用于后续打包的签名 stub；Windows 收到这些编译产物后加入已 Cook 内容，完成最终 IPA 的重新打包和签名。因此，最终交付目录在 Windows，并非“把所有 Cook 产物再送回 Mac 才能生成 IPA”。[3][4][5]

收益与成本

性能取舍属于工程判断，没有固定加速倍数。比较时用相同项目、配置、资源、SDK 和冷 / 热缓存；不要拿远程缓存命中与 Mac 每次从零编译整个引擎作比较。[1][6]

选型建议： Windows 是团队主要开发平台时，使用 Windows + 主构建 Mac；个人以 iOS SDK 和 Xcode 调试为主、Mac 性能足够时，纯 macOS 通常更容易维护。下面完成 Windows 路线的全部交付步骤。

面向 Windows 团队的推荐架构

在UE 5.6、Windows为主要开发平台、需要完整IPA/dSYM交付的前提下，推荐“一台Windows负责一个iOS构建任务，单机Cook调优，团队共享派生数据，Mac原生构建按资源排队”。 这是基于官方能力和维护成本的工程选择；具体进程数及硬件配置需用项目实测，没有跨项目通用的“最快参数”。

上表中Horde和多进程Cook的边界由官方文档明确支持；Mac的起步并发、缓存优先顺序属于本指南建议。UE5.6没有默认的远程Cook Worker机制，不能把一个iOS包的资源自动分给多台Windows Cook后汇总。 不同平台/项目的独立任务可以并行，一次Cook的多个Worker是单机并行。[16][17][20]

先用第2至第8章完成单任务交付，再按第6.5节调优单机Cook，最后按第6.6节接入团队调度与缓存。多机增加的是独立任务吞吐量；不会自动缩短同一个iOS Cook的关键路径。

第一次实践建议使用 Shipping + Ad Hoc：优化后的发布配置，Apple Distribution 签名，Profile 包含测试设备 UDID，可直接安装到这些已注册设备。先用 Development 跑通连接 / 签名，再切到 Shipping / Ad Hoc。[9][10]

Shipping 是编译配置，-distribution 是分发打包，Profile 决定签名用途。三者要匹配。App Store Profile 的包不能当作 Ad Hoc 包直接安装。[4][9][10]

工具版本

VS / MSVC 工具集需要满足 UE 5.6 官方兼容要求；不能只按“装了 VS”判断。.NET 组件按实际引擎安装处理。[7][8][9][11]

当前商店提交要求： Apple 自 2026-04-28 起要求上传 App Store Connect 的应用使用 Xcode 26 或更新版本和 iOS 26 等对应 SDK。Xcode 16.1 是 UE 5.6 文档基线，不能据此保证 2026 年的上架提交。若目标是当前上架，先完成 UE 5.6 分支与全部插件对所需新工具链的兼容验证，再使用本文 AppStore 模式。[13]

填好全文使用的参数

脚本针对 有自己 C++ Game Target 的普通 App。纯 Blueprint 会复用 UnrealGame 目标与符号；不要拿其他引擎版本的 dSYM 配它。要直接使用本文脚本，可先添加空 C++ 类，形成项目自己的 Game / Editor Target，并验证编辑器构建。Framework 输出、多 Target、自定义输出路径需按实际 receipt 调整。[6]

3.1 确认完整 Xcode 与 iOS SDK

打开 Xcode 完成首次启动、组件和许可证处理，安装 iOS 平台支持。在 Terminal 执行：

xcode-select -p
xcodebuild -version
xcodebuild -showsdks
xcrun --sdk iphoneos --show-sdk-path
xcodebuild -checkFirstLaunchStatus

检查点：Developer 路径指向完整 Xcode，版本正确，存在 iphoneos，首次启动检查通过。仅安装 Command Line Tools 不等于完整 iOS 构建环境。[8]

选错 Xcode 时，按真实路径切换并重新检查：

sudo xcode-select --switch /Applications/Xcode_16.1.app/Contents/Developer

示例路径必须替换。构建期间保持同一 Xcode / SDK；切换后重建、重验。

3.2 创建标识、签名与 Profile

在 Apple Developer 的 Certificates, Identifiers & Profiles 中：

1. 注册 App ID com.example.MyGame，启用实际 capabilities。
2. 登记测试设备 UDID。
3. 准备 Apple Development 证书和 iOS App Development Profile。
4. 准备 Apple Distribution 证书和 Ad Hoc Profile，加入测试设备。
5. 从 Keychain Access 导出证书及对应私钥为 .p12，设置密码；下载 .mobileprovision。

只有 .cer 不能代替含私钥的 .p12。按远程文档要求把签名身份装到 Mac 的 System Keychain，Profile 装到构建用户可访问的位置。[1][9][10]

Xcode 16 常用 Profile 目录：

~/Library/Developer/Xcode/UserData/Provisioning Profiles/

5.6.1 源码按 Xcode 版本识别该路径；不要只检查旧版的 ~/Library/MobileDevice/Provisioning Profiles/。[3]

确认 Mac 识别有效签名身份：

security find-identity -v -p codesigning

3.3 启用 Remote Login

Sonoma 中打开 System Settings > General > Sharing > Remote Login，允许构建账号登录。记录 IP / 用户，保证 Windows→Mac 22 端口互通，账号能写构建目录。[1]

默认远程根目录为 ~/UE5/Builds/<Windows机器名>；可设置 RemoteServerOverrideBuildPath。真实目录以 [Remote] Using base directory ... 日志为准。[1][3]

官方推荐先在 Mac 本地构建一次，排除工具链 / 签名问题。如果临时用 UE 做这一检查，它与“日常远程 Mac 不必预装完整 UE”并不冲突。[1]

4.1 Windows 编辑器先能正常构建

安装 UE iOS 支持与 VS C++ 组件，确认项目 C++ / 插件的 Win64 编辑器模块可构建，地图可打开。本文示例的 Editor 构建：

$EngineRoot = 'C:\Epic\UE_5.6'
$ProjectFile = 'D:\UEProjects\MyGame\MyGame.uproject'
& "$EngineRoot\Engine\Build\BatchFiles\Build.bat" `
    MyGameEditor Win64 Development "-Project=$ProjectFile" -WaitMutex
if ($LASTEXITCODE -ne 0) { throw 'Windows Editor build failed' }

MyGameEditor 要替换为真实 Editor Target。这是编辑 / Cook 前置准备，不生成 iOS IPA。[7][11]

安装官方要求的 iTunes / iOS 支持组件与 Metal Developer Tools 4.4。[1][8]

4.2 Windows 导入 .p12 与 .mobileprovision

先确保构建账号能使用并导出签名私钥。 “P12 含私钥”“已导入 Windows”和“Windows 私钥可导出”是三个条件；缺少最后一个条件，会影响远程构建导出临时签名材料。[3][15]

在执行 UE / UAT 的 同一个 Windows 用户账号 下，双击受控位置的 .p12，打开证书导入向导：

1. 存储位置选择“当前用户（Current User）”，输入 P12 密码。
2. 在私钥相关选项中勾选 “将此密钥标记为可导出（Mark this key as exportable）”。
3. 将证书导入当前用户的“个人（Personal）”证书存储区，完成导入。[15]

如果已经通过 UE 的 Certificate 导入按钮安装了 P12，也要完成下面的检查。不要只看 UE 的绿色有效状态就跳过私钥可导出确认。向导要求选“可导出”，不等于此刻需要额外导出一份私钥文件。

导入后的手工检查：

1. 按 Win + R，输入 certmgr.msc，打开 个人 > 证书。
2. 找到与本轮 Profile 匹配的 Apple Development / Apple Distribution 证书，打开证书，确认显示具有对应私钥。
3. 右键该证书，选择 所有任务 > 导出。检查 “是，导出私钥（Yes, export the private key）” 是否可选，然后取消向导；此项不可选时，先确认私钥是否存在、是否属于当前构建账号以及导入时是否设为可导出。
4. 若原导入不符合要求，使用原始 P12 和密码按上述设置重新导入，重新检查；无原始私钥时回到签名材料管理者处理，单独下载 .cer 无法补出私钥。[15]

接着打开 Project Settings > Platforms > iOS，设置 Bundle Identifier，用 Provision 按钮导入 .mobileprovision，手动选择已安装的对应证书和 Profile，并确认有效。SigningCertificate 使用 UE 实际识别的证书名称；P12 文件名是导入材料，不应通用地写成证书名称。[3][9]

5.6.1 远程代码会在 Windows 找 Profile、导出临时 P12 并送到 Mac；最终 Windows iPhonePackager 的重新签名也使用对应身份。只在 Mac 安装证书，不能完成本文的 Windows 手工签名路线。CI 的账号若与桌面用户不同，需要在 CI 执行账号的证书上下文重新确认上述条件。[3][4][9]

随附 Build-IOS.ps1 -DryRun 检查项目参数与配置，不会代替这项证书存储区 / 私钥可导出检查。

Windows Profile 常用目录：

%LOCALAPPDATA%\Apple Computer\MobileDevice\Provisioning Profiles\

MobileProvision / ProvisionFile 要填实际安装的文件名，而不是 Apple 页面上的显示名。[3]

4.3 生成并测试 UE 的 SSH Key

在 Remote Build 设置填 192.168.1.20、用户名 uebuild，关闭 Enable Secondary Remote Mac，点击 Generate SSH Key 并完成安装。第一次连接确认目标机器与主机指纹，密钥位置以 UE 显示值为准。[1]

默认候选路径：

%APPDATA%\Unreal Engine\UnrealBuildTool\SSHKeys\192.168.1.20\uebuild\RemoteToolChainPrivate.key

先测端口：

Test-NetConnection -ComputerName 192.168.1.20 -Port 22

再用 UE 随附 cwrsync SSH 测密钥；替换路径 / 用户：

$EngineRoot = 'C:\Epic\UE_5.6'
$RemoteHost = 'uebuild@192.168.1.20'
$Key = Join-Path $env:APPDATA `
    'Unreal Engine\UnrealBuildTool\SSHKeys\192.168.1.20\uebuild\RemoteToolChainPrivate.key'
$KeyForCygwin = '/cygdrive/' + $Key.Substring(0, 1).ToLower() + `
    ($Key.Substring(2) -replace '\\', '/')
& "$EngineRoot\Engine\Extras\ThirdPartyNotUE\cwrsync\bin\ssh.exe" `
    -i $KeyForCygwin -o BatchMode=yes $RemoteHost 'xcodebuild -version'
if ($LASTEXITCODE -ne 0) { throw 'UE SSH / Xcode preflight failed' }

预期无需交互就能输出目标 Mac 的 Xcode 版本。系统 OpenSSH 通过不代表 UE 的 cwrsync / 密钥权限也通过。[3]

UNPROTECTED PRIVATE KEY FILE / 0660 按官方文档修复密钥权限，再测试。私钥 / P12 保存在受控凭据位置，不放到网站或公开仓库。[1]

5.1 开启完整 dSYM Bundle

Project Settings > Platforms > iOS > Build 启用两个选项：

• Generate dSYMs for code debugging and profiling。
• Generate dSYMs as a bundle for third party crash tools。[2]

第一个启用生成，第二个输出标准目录形式的 .dSYM Bundle，并生成可回传的 .dSYM.zip。[2][3]

本文单主 Mac、手工签名的 Config/DefaultEngine.ini：

[/Script/IOSRuntimeSettings.IOSRuntimeSettings]
BundleIdentifier=com.example.MyGame
RemoteServerName=192.168.1.20
RSyncUsername=uebuild
bUseRSync=True
bSupportSecondaryMac=False
bAutomaticSigning=False
MobileProvision=MyGame_AdHoc.mobileprovision
SigningCertificate="Apple Distribution: Example Company (ABCDE12345)"
bGeneratedSYMFile=True
bGeneratedSYMBundle=True
bGenerateXCArchive=False
bShipForBitcode=False

首次 Development 换成 Development Profile / 证书，Ad Hoc 再换回 Distribution 身份。bGenerateXCArchive=False 与 dSYM 生成无关；Windows 的该选项不能生成 XCArchive。[3][4]

不要在 Config/IOS/IOSEngine.ini 等位置覆盖成不同值。脚本以 DefaultEngine.ini 为实践配置来源；已有平台覆盖需先明确有效配置再调整检查。

5.2 配置实际发布内容

在 Project Settings > Packaging：选对应 Build Configuration；Ad Hoc / App Store 勾 For Distribution，Development 取消；Pak / IoStore 与 UAT 参数一致；实际发布地图进入 Maps to Cook，Game Default Map 正确；动态 / 软引用资源通过 Asset Manager、Primary Asset Label 或额外 Cook 目录覆盖。[11]

Config/DefaultGame.ini 示例：

[/Script/UnrealEd.ProjectPackagingSettings]
BuildConfiguration=PPBC_Shipping
ForDistribution=True
bUsePakFile=True
bUseIoStore=True
+MapsToCook=(FilePath="/Game/Maps/Main")

/Game/Maps/Main 是占位地图。编辑器可运行不代表 Cook 资源完整；实际登录、支付 / SDK 资源、关卡和动态加载路径都要验收。

5.3 固定 stub → Windows IPA 流程

本文显式使用 -legacyxcode，并用 -ubtargs=-legacyxcode 传给 UBT / 远程编译端，固定已核对的路线，不要求改引擎 BaseEngine.ini。不要同时传 -modernxcode。[3][4]

6.1 构建实际做什么

1. Windows UAT / UBT 读项目、目标、Profile 和签名配置。
2. 所需构建文件和签名材料同步到主 Mac。
3. Mac 编译 / 链接 iOS C++，生成 dSYM 和签名 stub；产物按 manifest 回传。
4. Windows Cook 内容，Stage 组织发布资源。
5. Windows iPhonePackager 把内容加入 stub，按配置签名最终 IPA。
6. UAT Archive 收集 IPA，随后独立收集本次 receipt 的 dSYM ZIP。[3][4][11]

6.2 Shipping / Ad Hoc 完整 UAT 命令

使用 PowerShell，替换变量，确保上一章已选 Ad Hoc 签名：

$EngineRoot = 'C:\Epic\UE_5.6'
$ProjectFile = 'D:\UEProjects\MyGame\MyGame.uproject'
$TargetName = 'MyGame'
$ArchiveDir = 'D:\IOSDeliveries\MyGame-AdHoc-FirstBuild\UATArchive'
$UatArgs = @(
    'BuildCookRun', '-installed', '-nop4',
    "-project=$ProjectFile", "-target=$TargetName",
    '-platform=IOS', '-clientconfig=Shipping',
    '-build', '-cook', '-stage', '-pak', '-iostore',
    '-package', '-distribution', '-archive', "-archivedirectory=$ArchiveDir",
    '-nodebuginfo', '-unattended', '-utf8output',
    '-legacyxcode', '-ubtargs=-legacyxcode',
    '-provision=MyGame_AdHoc.mobileprovision',
    '-certificate=Apple Distribution: Example Company (ABCDE12345)'
)
& "$EngineRoot\Engine\Build\BatchFiles\RunUAT.bat" @UatArgs
if ($LASTEXITCODE -ne 0) { throw 'UAT failed: inspect the earliest failed stage' }

此处 -nodebuginfo 把符号与 App 内容分开。第五章开启生成，第七章从原始 Binaries / receipt 收集；不要把这个参数理解成“完全不生成 dSYM”。[3][4]

6.3 用随附脚本一起完成构建和收集

把 Build-IOS.ps1 与 Verify-IOS.py 放在同一目录，如 D:\BuildTools\UE56IOS\。脚本检查版本 / 关键配置，创建唯一输出目录，保存日志，检查 UAT 返回值，按本次 receipt 收集 dSYM ZIP，并生成哈希清单。

先预览：

& 'D:\BuildTools\UE56IOS\Build-IOS.ps1' `
    -EngineRoot 'C:\Epic\UE_5.6' `
    -ProjectFile 'D:\UEProjects\MyGame\MyGame.uproject' `
    -TargetName 'MyGame' `
    -BundleIdentifier 'com.example.MyGame' `
    -ProvisionFile 'MyGame_AdHoc.mobileprovision' `
    -SigningCertificate 'Apple Distribution: Example Company (ABCDE12345)' `
    -OutputRoot 'D:\IOSDeliveries' `
    -Mode AdHoc -DryRun

确认后去掉 -DryRun 执行。源码引擎加 -SourceEngine。如果团队 PowerShell 策略限制脚本，按团队已有授权方式执行，不要全局放宽策略。

Development 用 -Mode Development、Development 证书 / Profile，并同步改项目设置；AppStore 同理。只改 -Mode 不够，远程编译读取的项目签名配置也必须匹配。

脚本的 -CookProcessCount 默认1，明确固定基线。完成第6.5节的比较后，可在同一调用增加 -CookProcessCount 4，或使用实际有效的其他值。该参数经UAT的AdditionalCookerOptions传给本机Cooker，不会创建另一台Windows上的Worker。[16]

6.4 判断本次成功

检查日志中的 Mac / 用户、base directory、Xcode / SDK、编译和链接、dSYM 生成、Downloading build products、Cook、iPhonePackager、Package 与 Archive，最终成功退出。[3][4]

独立输出目录、当前日志、receipt 和第八章 UUID 核验一起排除旧产物。“目录里已有一个 IPA”不能证明本次成功。

6.5 首次交付通过后，再选择 Cook 优化

先按默认主线完成一轮 IPA / dSYM 收集、签名和 UUID 核验以及真机验收，再根据项目耗时选择优化。下面选项在 UE 5.6.1 UAT 中可用，属于不同层面的配置，不是生成 IPA / dSYM 的必需参数。[4]

ZenStore 的角色是 Cook 输出存储；增量 Cook 的角色是资源结果复用。使用 -pak -iostore 打包后，应确认运行需要的资源已包含在交付包中，并在目标设备不连接开发用 Zen 服务的条件下验证启动与关键资源加载。[4][11]

要在第 6.2 节的 直接 UAT 命令 上尝试，放在 $UatArgs 定义之后、RunUAT.bat 调用之前。按需取消对应行的注释，逐项验证，不必全部启用：

# 可选：Zen 服务与 Cook 输出存储已准备好
# $UatArgs += '-zenstore'
# 可选：已有兼容 Cook 缓存
# $UatArgs += '-iterativecooking'
# 可选：测试资源容器压缩的包体与加载表现
# $UatArgs += '-compressed'

本版 Build-IOS.ps1 保留基础构建参数，没有 -ZenStore / -IterativeCooking 开关；上面的示例修改的是直接 UAT 参数数组，不能把这些开关直接传给辅助脚本。

优先验证单机多进程Cook，再决定是否使用Zen Cook输出和增量Cook。 官方将多进程Cook列为Beta功能：更多Worker会使用更多内存，CPU/内存饱和或GC频繁会使Cook更慢；聚合多个包数据的插件也可能需要IMPCollector适配。小项目保持1个进程可能更快，World Partition等场景应特别检查Worker负载和日志。[16]

选择一种设置方式，避免互相覆盖：

; Config/DefaultEditor.ini
[CookSettings]
CookProcessCount=4

使用直接UAT命令时，在第6.2节调用前追加：

# 整个参数是一个PowerShell数组元素
$UatArgs += '-AdditionalCookerOptions=-cookprocesscount=4'

若已有AdditionalCookerOptions，应把 -cookprocesscount=4 合并到原来那个参数中。使用本文脚本时直接传 -CookProcessCount 4；脚本每次明确传入该值，默认1会覆盖DefaultEditor.ini中的默认进程数。4只是起始比较值，不是“4台Windows”。[16]

希望复用原生编译缓存时，不要每次构建前都删除 Intermediate\Build\IOS；该目录与 Cook 缓存的职责不同。只清掉原生中间结果、同时启用 -iterativecooking，只能说明资源侧可能增量，不代表 C++ 编译也增量。定位缓存问题时可以按实际失败阶段清理相关缓存，但清理后的第一次构建耗时应单独记录。[3][4]

优化后仍保留相同的交付条件：最终 IPA、该次主程序 dSYM ZIP、receipt、日志、签名 / UUID 核验以及设备测试。测量时分别记录原生编译、Cook、打包和同步耗时，不能用一个“总耗时变短”推断所有阶段都变快。

6.6 团队落地：任务调度、缓存与Mac资源

第一步：先确定优化单次耗时，还是增加团队吞吐量

一个项目的单次iOS发布慢，先分析Mac编译、Windows Cook、同步、打包各阶段；只有Cook是主要瓶颈时，优先调Cook进程与资源缓存。多个独立构建排队时，才增加Windows Agent或拆分不同平台任务。没有必要仅为一个iOS任务先搭建整个Horde服务。

本指南推荐起步拓扑：

现有CI，或Horde Server + BuildGraph
  ├─ Windows Agent A：本次iOS任务
  │    ├─ Cook Director + 本机Cook Worker
  │    ├─ SSH使用指定Mac A：C++ / Link / dSYM / stub
  │    └─ 本机Stage / IPA / 符号收集
  ├─ Windows Agent B：Android或另一项独立构建
  └─ Windows Agent C：Win64、编辑器或独立测试任务

同一机房的Agent → 已配置的Shared DDC
每次交付产物    → CI/Horde产物库或团队归档
最终iOS交付     → Mac签名/UUID核验 → 真机验收

这是任务分工建议，不是Horde自动生成的流水线。A的Cook Worker全部在A机器上；B、C不参与A的这一轮iOS资源拆分。[16][17]

第二步：明确三类数据，优先配置Shared DDC

Shared DDC不等于Cook资源分片，也不等于最终包仓库。 -zenstore 控制Cook输出存储；配置共享Zen DDC无需因此给每次UAT加 -zenstore。UE5.4及以后默认本地DDC使用Zen；新建同区域团队服务可以评估Windows共享Zen，已有稳定文件共享DDC先复用，跨地域再考虑Cloud DDC。[18][19]

下面示例以管理员已按官方文档部署并验证可访问的共享Zen服务为前提，替换主机与namespace；只在项目 Config/DefaultEngine.ini 加客户端配置，不修改iOS签名部分：

[StorageServers]
Shared=(Host="http://shared-ddc.example.internal:8558", Namespace="mygame.ddc", EnvHostOverride=UE-ZenSharedDataCacheHost, CommandLineHostOverride=ZenSharedDataCacheHost, DeactivateAt=60)

标准UE配置中的ZenShared通过ServerID=Shared使用这一项。启动编辑器/构建，检查 LogDerivedDataCache 出现ZenShared、期望主机和namespace以及可用状态；在编辑器的Derived Data / View Cache Statistics检查延迟。自定义DDC图需确认保留ZenShared节点；不可只写一行配置就认定生效。[18][19]

Zen共享DDC在UE5.6的官方适用范围是可信LAN/VPN：服务没有认证，配置与访问限于团队既有可信网络。它不是要公开到公网的交付服务。官网给出了专门的服务端安装、数据目录、启动和客户端核验步骤；本文没有实际部署该服务。[19]

Horde发布任务的工作区可以回到干净状态，但DDC缓存可以在工作区之外或共享服务中复用。这与日常 -iterativecooking 依赖Cook输出复用不同；“干净发布工作区 + Shared DDC”仍有缓存收益。[17][18]

第三步：已使用Horde时，按独立任务配置BuildGraph

UE5.6官方构建自动化教程以Perforce Stream、Horde Server及Agent为前提；已有其他CI的团队可先继续调用本文脚本，采用相同的工作区、缓存和Mac资源规则，无需为Cook性能强行迁移。[17]

Horde落地时按以下顺序配置与验证：

1. 用同一修订的引擎、项目、插件和构建脚本定义BuildGraph节点；明确每个节点的输入、输出和依赖。
2. 在Horde配置project、stream、agent type及job template；agent type映射到实际机器池和工作区。
3. 起步为iOS任务使用专用Windows Agent池，配对指定Mac；其他池执行Android/Win64等独立任务。
4. Build → Cook → Stage → Package → 收集IPA/dSYM 起步保持在同一个Windows Agent组内，避免搬运未明确声明的Binaries/receipt/Cook状态。它内部仍会通过SSH使用Mac。
5. 同一份完整delivery交给Mac核验节点或现有Mac验证任务，成功后才归档/分发。跨Agent步骤显式声明产物，不能只依赖源机器上的临时目录。[17][20]

同一个BuildGraph Agent组内节点顺序执行、保留中间目录；独立Agent组按依赖可并行。将Build与Cook进一步拆到不同机器之前，应先明确全部原生编译产物、receipt、插件资源和Cook数据的传输契约，而不是只复制一个IPA或一个Content目录。[20]

第四步：让Mac排队规则覆盖SSH远程构建

Horde租用了Windows Agent，不等于它自动租用了该任务经SSH连接的Mac。推荐起步每台Mac对应一个专用Windows iOS Agent，同一时刻只运行一个iOS任务；其他Windows仍可并行其他平台任务。其他CI任务、开发者直接运行UAT也应遵守同一Mac排队规则。

需要更多iOS并发时，优先增加经验证的Windows/Mac配对，或实现覆盖所有入口的Mac资源锁，再评估账号、Keychain、工作目录、网络和内存隔离。不能让多个Windows仅填写同一个RemoteServerName就认为并发安全。此为本指南基于共享签名和远程工作区的工程建议，不是Horde默认替你执行的限制。[3][17]

第五步：用实测选参数

先记录单进程基线，再比较1、2、4个Cook进程，保证同一代码/资源修订、平台、配置及缓存条件。分别记录总耗时、Cook耗时、Mac编译、同步、打包、峰值内存、GC和Worker错误。稳定减少关键阶段耗时且通过交付验收的值才进入日常模板。[16]

Horde提高任务吞吐量，单机多进程Cook缩短可能的Cook阶段，DDC减少重复派生数据工作。三者结合形成推荐方案；它们不是跨机器Cook Worker，不能承诺把同一个iOS全量构建按机器数量线性加速。

7.1 原始产物位置

普通 C++ Game、Target MyGame 的典型结果：

D:\UEProjects\MyGame\Binaries\IOS\
  Distro_MyGame-IOS-Shipping.ipa
  MyGame-IOS-Shipping.dSYM.zip
  MyGame-IOS-Shipping.target

名字受 Target、配置、架构和项目类型影响，以本次 receipt / 日志为准，不在所有项目硬编码。[3][4]

脚本从本次 UATArchive 找最终 IPA，从对应 *.target 的 BuildProducts 找符号。不要手选其他配置 / Target 的同名文件。

7.2 为什么 -archive 不够

5.6.1 Windows Legacy GetFilesToArchive 收集 IPA；dSYM ZIP 属于 Mac 编译产物，由 dsymutil 生成，按 manifest 回传，需要独立收集。[3][4]

符号 ZIP 应保留完整 Bundle：

MyGame-IOS-Shipping.dSYM/
  Contents/
    Info.plist
    Resources/
      DWARF/
        MyGame-IOS-Shipping

保留原始 .dSYM.zip，在 Mac 用 ditto 解包，避免 Windows 复制改变结构或符号链接。崩溃平台需要 Bundle / ZIP 时，上传与该 IPA 配对的一份。[3][12]

7.3 交付结构

MyGame-Shipping-AdHoc-<时间>-<唯一ID>/
  build.log
  UATArchive/
    ...本次 UAT 的 IPA...
  delivery/
    Distro_MyGame-IOS-Shipping.ipa
    symbols/
      MyGame-IOS-Shipping.dSYM.zip
      ...receipt 列出的其他 dSYM ZIP...
    build.target
    Build.version
    build.json
    build.log
    artifact-manifest.json
    Verify-IOS.py
    verification.json   ← 第八章成功后生成

收集完成只表示文件存在、有哈希。build.json 标记尚未通过签名 / UUID 核验；成功核验后才确认主程序符号与最终包匹配。

7.4 第三方动态 Framework 的符号

主程序 dSYM 不覆盖每个独立动态 Framework。需要供应商提供 与该 Framework 二进制 UUID 匹配 的 dSYM。参与主程序静态链接的代码与独立 Framework 要区分。[12]

需要 SDK 符号时，先把该版本供应商的 .dSYM.zip 放进独立目录，构建脚本增加 -AdditionalSymbolDirectory 'D:\SDKSymbols\CurrentVersion'。脚本将其与 UE 符号一起收集并生成哈希清单，然后运行 --require-framework-symbols。如果供应商只有 .dSYM 目录，可先在 Mac 用 ditto -c -k --keepParent Foo.framework.dSYM Foo.framework.dSYM.zip 保留 Bundle 打包。脚本不会凭空生成供应商已剥离的符号。

8.1 传输整个交付目录

用团队已有文件共享 / SFTP 工具，把 delivery/ 整体复制到 Mac，如 ~/IOSDeliveries/MyGame-AdHoc/，保持 IPA、原始 dSYM ZIP、receipt 和 manifest 一起移动。

8.2 运行核验脚本

替换 Bundle ID、Team ID、设备 UDID：

python3 "$HOME/IOSDeliveries/MyGame-AdHoc/Verify-IOS.py" \
  "$HOME/IOSDeliveries/MyGame-AdHoc" \
  --bundle-id com.example.MyGame \
  --team-id ABCDE12345 \
  --mode ad-hoc \
  --device-udid YOUR_REGISTERED_DEVICE_UDID

脚本核对文件哈希、ZIP 完整性、receipt、Bundle ID、arm64、主程序与 dSYM 全部 UUID / 架构、代码签名、Profile 有效期、Team、签名模式和设备覆盖。它不会重新签名、修改 IPA 或安装应用。

成功生成 verification.json，列出 IPA 哈希与 UUID，并明确 真机验收尚待执行。需要完整动态 Framework 符号覆盖时，在同一命令最后加 --require-framework-symbols。默认报告会列出 Framework 符号缺口；主程序匹配不等于所有 SDK 符号齐全。

8.3 手工检查 UUID 的命令

替换 IPA、符号 ZIP、.app 的真实文件名：

Delivery="$HOME/IOSDeliveries/MyGame-AdHoc"
CheckDir=$(mktemp -d /tmp/mygame-verify.XXXXXX)
ditto -x -k "$Delivery/Distro_MyGame-IOS-Shipping.ipa" "$CheckDir/ipa"
ditto -x -k "$Delivery/symbols/MyGame-IOS-Shipping.dSYM.zip" "$CheckDir/symbols"
App="$CheckDir/ipa/Payload/MyGame.app"
Executable=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' "$App/Info.plist")
xcrun dwarfdump --uuid "$App/$Executable"
xcrun dwarfdump --uuid "$CheckDir/symbols/MyGame-IOS-Shipping.dSYM"
codesign --verify --deep --strict --verbose=2 "$App"
security cms -D -i "$App/embedded.mobileprovision" > "$CheckDir/profile.plist"
/usr/libexec/PlistBuddy -c 'Print :Name' "$CheckDir/profile.plist"
/usr/libexec/PlistBuddy -c 'Print :ExpirationDate' "$CheckDir/profile.plist"

先看 Payload/ 再设置 App；两个 dwarfdump 的 UUID / 架构逐项一致。文件名相同、时间接近、都是 Shipping 都不能替代配对。[12]

8.4 真机安装与功能验收

Ad Hoc / Development 通过 Xcode Window > Devices and Simulators 或团队设备工具安装。检查 UDID 覆盖，完成设备所需开发者模式 / 信任，再启动。[9][14]

至少验收：启动地图、登录 / 支付 / SDK 初始化、网络与权限、关键关卡、动态资源加载、真实设备画面与性能。安装、启动、符号核验分别记录。需要符号化验收时，用可控测试崩溃或已知报告验证崩溃平台的 UUID 与堆栈解析。[12]

8.5 App Store / TestFlight 分支

先满足第二章工具链要求与项目兼容性，再换 App Store 证书 / Profile，脚本 -Mode AppStore，Mac 核验 --mode app-store，无需设备 UDID。该 IPA 用于渠道提交，不做 Ad Hoc 安装。

用团队提交工具或 Mac Transporter 提交 IPA，保留本版本 dSYM、日志、receipt 和报告。Windows Legacy 已生成 IPA，不必为“得到 IPA”重新完整 Mac 构建；团队另需 .xcarchive 时，再规划 Mac Modern / Archive 交付。[6][10][13]

交付完成核对

勾选记录开发者实际执行结果，网站不会自动检测 UE 环境。

• Windows 指定 UE 5.6，Mac 实际 Xcode / SDK 已核对。
• Windows 构建账号的证书含可导出私钥，Profile / Bundle ID / 模式与设备覆盖匹配。
• 本次 Windows UAT 构建、Cook、Package、Archive 成功。
• delivery 含最终 IPA、完整主程序 dSYM ZIP、receipt、日志和版本。
• 最终IPA签名 / Profile通过，全部主程序UUID与dSYM对应。
• 若要求SDK符号覆盖，动态Framework匹配dSYM已补齐。
• AdHoc / Development已在目标真机安装、启动并通过关键功能。
• 若为当前AppStore提交，满足当期工具链并完成渠道验证。

Epic GitHub需要关联Epic的账号权限。网站不包含引擎源码或签名材料；随附脚本是独立工程模板。

官方文档和指定源码已核对。网站、下载及脚本参数 / 核验逻辑可单独验证；真实UE编译、Windows证书导入、Mac远程构建、IPA运行和新SDK兼容性，需要开发者在自己的环境按检查点完成，不能把网站发布当成这些验收通过。