在 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]

收益与成本

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

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

第一次实践建议使用 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

打开 Project Settings > Platforms > iOS：

1. 设置 Bundle Identifier。
2. 用 Provision 导入按钮导入 .mobileprovision。
3. 用 Certificate 导入按钮导入含私钥的 .p12，在提示框输入密码。
4. 手动选本轮对应的 Profile / 证书，确认 UE 显示有效状态。

Windows 要有可使用的签名私钥。 5.6.1 远程代码会在 Windows 找 Profile、导出临时 P12 并送到 Mac；最终 Windows iPhonePackager 的重新签名也使用对应身份。只在 Mac 安装证书，不能完成本文的 Windows 手工签名路线。[3][4][9]

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 不够，远程编译读取的项目签名配置也必须匹配。

6.4 判断本次成功

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

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

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 已核对。
• 证书含私钥，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兼容性，需要开发者在自己的环境按检查点完成，不能把网站发布当成这些验收通过。