iOS 打包机迁移要备份什么？2026 Xcode 27 清单

iOS 打包机迁移要备份什么？2026 Xcode 27 清单

迁移 iOS 打包机时，不能只复制项目目录或重新安装 Xcode；只有新环境独立完成源码解析、Xcode 27 构建、Archive、签名、上传和恢复测试，旧主机才适合清理或退租。这个标准适用于需要更换远程 Mac、重建持续集成节点，或接手旧发布环境的独立开发者和小型团队。

最后更新于 2026 年 9 月 8 日，版本与行为核实自 Apple Developer 官方文档及自托管 Runner 官方说明。截至该日期，Apple 官方系统要求页面列出的是 Xcode 27 beta 4，要求 macOS Tahoe 26.4 或更高版本，并支持 iOS 27 SDK；正式版要求不能提前假设，应以迁移当天的官方页面为准。查看 Xcode 27 系统要求

这篇文章适合三类人：

  • 准备退租远程 Mac，却不确定哪些资产必须带走的独立开发者；
  • 需要把 Xcode 27 构建任务迁移到另一台 Mac 的持续集成维护者；
  • 接手外包项目或重建故障打包机，需要确认发布链路可以恢复的小型团队。

迁移成功标准

项目已经出现在新 Mac 上，不代表迁移完成。真正需要验证的是：新环境不依赖旧主机的用户目录、钥匙串、缓存目录或后台进程，也能从干净检出开始完成一次可发布构建。

建议先从最近一次成功发布记录建立基线。不要只记录“构建成功”，而要保存以下信息：

  • Xcode 版本、macOS 版本和命令行工具路径；
  • Scheme、Configuration、Destination 与 Archive 导出方式；
  • Bundle ID、Team ID、版本号和构建号；
  • 依赖锁文件的解析结果；
  • 使用的签名身份、Provisioning Profile 和上传方式；
  • 归档 UUID、IPA、dSYM 与上传记录；
  • CI 任务名称、Runner 标签、环境变量名和日志位置。

可以在旧 Mac 上执行以下命令，输出结果脱敏后放进迁移记录：

xcodebuild -version
xcode-select -p
xcodebuild -showsdks
xcodebuild -list -workspace App.xcworkspace

示例输出：

Xcode 27.0
Build version 18AXXXX
/Applications/Xcode.app/Contents/Developer
iOS 27.0 -sdk iphoneos27.0

这里的版本输出只是记录格式示例，不应把示例中的 Build version 当成固定值。迁移时应保存实际输出，并在新环境重新执行同一组命令。

源码与工具链基线

可重建的构建输入

源码通常可以从版本库重新检出，但以下内容经常没有进入版本库，却会直接影响 Archive：

  • Git 子模块及其固定提交；
  • Swift Package Manager、CocoaPods 或其他依赖的锁文件；
  • 私有仓库的访问方式；
  • 构建脚本、签名脚本和自定义工具；
  • .xcconfig、环境配置和未提交的生成文件；
  • 本地化资源、隐私清单、脚本输入和构建阶段依赖；
  • 需要在 CI 中注入的环境变量名称。

迁移时应区分“可以重新下载”和“必须随迁移保存”。依赖源码通常可以根据锁文件重新解析，但私有仓库权限、内部二进制包地址和脚本使用的变量名，可能只存在于旧主机或旧 Runner 配置中。

新环境不要直接复制 DerivedData 作为主要恢复方案。DerivedData 可以帮助排查问题，却不能替代干净检出。正确的验收动作是：

git clone --recursive https://example.invalid/REDACTED/app.git app-migration-test
cd app-migration-test

xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  -resolvePackageDependencies

通过标准不是命令返回了几行日志，而是：

  1. 依赖可以在不读取旧主机目录的情况下解析；
  2. 私有依赖访问失败时，日志能明确指出权限问题；
  3. Scheme 和构建配置与最近一次成功发布一致；
  4. 生成的构建输入可以被团队成员复核。

Xcode 27 路径与配置记录

Xcode 27 的系统要求必须单独记录。不要只记“已经安装 Xcode 27”，因为同一主版本下可能存在不同 Beta、RC 或正式版。Apple 的系统要求页面列出支持的 macOS、SDK、部署目标、模拟器和 Swift 编译器信息，迁移前后应分别保存版本记录。

项目入口也要固定。以下项目容易被忽略：

  • 工作区与项目文件是否使用相同 Scheme；
  • Archive 使用的是设备目标，而不是普通模拟器运行目标；
  • Release 配置是否引用了不同的 .xcconfig；
  • 构建脚本是否依赖固定的绝对路径；
  • 自定义工具是否通过 Homebrew、脚本目录或环境变量提供。

Xcode 的 Archive 不是普通 Debug 构建。它会把应用二进制和调试信息放进归档包，再通过 Organizer 执行验证、导出或上传流程。查看 Apple 的 Archive 与分发流程

签名身份与发布凭据

Apple Distribution 的完整性

迁移签名环境时，必须把以下对象分开核对：

  • Apple Distribution 证书；
  • 与证书匹配的私钥；
  • Provisioning Profile；
  • Bundle ID 与能力配置；
  • 钥匙串访问权限；
  • Xcode 自动签名或手动签名状态。

只导出 .cer 文件是不够的。证书文件本身不包含私钥，新的 Mac 即使能显示证书名称，也可能在 Archive 时提示没有对应的 signing identity。包含证书和私钥的身份通常通过加密的 PKCS #12 文件保存，Apple 官方文档也将这类身份作为敏感对象处理。查看身份导入与 PKCS #12 说明

在旧 Mac 上导出前，先确认钥匙串中证书和私钥处于同一身份下。备份包、密码和恢复说明不要放在同一个共享目录里。

在新 Mac 上导入后，可以使用以下命令检查签名身份：

security find-identity -v -p codesigning

示例输出：

1) 0000000000000000000000000000000000000000
   "Apple Distribution: REDACTED TEAM"
   1 valid identities found

输出中出现身份名称并不等于迁移通过。还必须使用目标项目和目标分发方式执行一次 Archive。Provisioning Profile 可以从开发者账户重新下载，但重新生成配置文件并不能自动恢复旧私钥。查看 Provisioning Profile 管理规则

撤销与轮换的影响

证书撤销不是普通清理动作。撤销后，依赖该身份的旧构建、自动化任务或团队成员可能受到影响。因此迁移记录中至少应写明：

  • 哪个证书会被撤销；
  • 哪些 Bundle ID 和工作流正在使用；
  • 新证书是否已经完成真实 Archive；
  • 失败时如何切回旧环境；
  • 旧主机何时停止使用该身份。

如果使用自动签名，不能把“Xcode 能自动下载配置文件”当作完整备份。自动签名可能在新环境生成不同的配置结果，导致能力、设备范围或发布方式发生变化。

App Store Connect API 凭据

自动上传通常还依赖 API Key、Key ID、Issuer ID 或其他上传凭据。Apple 说明，App Store Connect API 私钥下载后不会由 Apple 保留，私钥丢失或泄露时，需要撤销并重新生成。查看 App Store Connect API Key 管理规则

迁移记录中应保存“凭据恢复说明”，而不是把私钥直接写入普通文档：

APPSTORE_KEY_ID=REDACTED
APPSTORE_ISSUER_ID=REDACTED
APPSTORE_PRIVATE_KEY_PATH=/secure/path/AuthKey_REDACTED.p8
TEAM_ID=REDACTED
BUNDLE_ID=com.example.redacted

需要注意，Key ID、Issuer ID 和私钥必须属于同一组凭据。JWT 的签名私钥、令牌有效期和上传工具配置也要一并核对。不要把 .p8 文件提交到代码仓库、聊天记录或公开日志中。

归档产物恢复能力

xcarchive、dSYM 与 IPA

三类产物不能互相替代：

  • xcarchive：包含归档后的应用、二进制和调试信息，可用于后续验证、导出和问题排查；
  • dSYM：用于将崩溃报告中的地址还原为函数名和代码位置；
  • IPA：是导出的应用包，适合安装或上传，但不一定包含完整的归档上下文。

正式发布版本对应的 xcarchive 应长期保存，dSYM 也应按版本号、构建号和 UUID 归档。只保存 IPA，往往无法完成后续崩溃分析或重新导出。

每次发布都应建立一条对应关系：

版本号：1.8.0
构建号：10800
归档 UUID：REDACTED-UUID
xcarchive：App-1.8.0-10800.xcarchive
dSYM：App-1.8.0-10800.dSYM
IPA：App-1.8.0-10800.ipa
上传状态：已上传，等待处理

可以通过以下命令检查 dSYM 的 UUID：

dwarfdump --uuid \
  "App-1.8.0-10800.xcarchive/dSYMs/App.app.dSYM"

示例输出：

UUID: REDACTED-UUID (arm64) App.app.dSYM

如果二进制 UUID 与 dSYM UUID 不匹配，保存再多 dSYM 也不能用于该版本的崩溃符号化。只有匹配的二进制和 dSYM 才能完成可靠的符号恢复。查看 Apple 的 dSYM 核对说明

备份副本的验证

备份完成后，不要只检查文件大小。至少执行以下三类验证：

  1. 能从备份中打开 xcarchive；
  2. 能读取归档中的版本号、构建号和 UUID；
  3. 能在新 Mac 上使用归档执行验证或导出测试。

正式发布记录还应与上传平台中的构建号对应。本地显示“上传完成”不等于线上已经处理完成，必须在 App Store Connect 中确认目标构建已经出现并可继续操作。

自动化接管能力

新 Runner 的隔离验证

自托管 Runner 迁移最容易出现“双节点同时接单”。旧 Runner 没有停止，新 Runner 又使用了相同标签，可能导致两个环境交替执行发布任务，甚至重复上传同一构建。

更稳妥的顺序是：

  1. 在新 Mac 安装 Runner，但先使用明显的迁移测试标签；
  2. 注入脱敏后的只读变量，运行源码检出和依赖解析；
  3. 运行不上传、不发布的 Archive 任务；
  4. 确认 Xcode、钥匙串和 API 凭据可以被任务读取；
  5. 暂停旧 Runner 接收新任务；
  6. 将新 Runner 切换到正式标签；
  7. 执行一次真实 Archive 和上传；
  8. 再移除旧 Runner 注册信息。

Runner 的名称、仓库、组织、标签和日志路径都应脱敏。不要把真实 Token、私钥路径或 Team ID 直接贴进迁移文档。

自托管 Runner 的“停止运行”和“永久移除”不是同一动作。停止程序只会让 Runner 处于离线状态，永久移除则会删除注册配置；无法访问旧主机时，也可以从管理界面强制移除。查看自托管 Runner 移除流程

权限分层

迁移时，至少要把以下权限分开：

  • 代码仓库读取权限；
  • 远程 Mac 登录权限；
  • 钥匙串解锁权限；
  • Apple Distribution 私钥使用权限；
  • App Store Connect 上传权限；
  • Runner 注册和移除权限。

如果所有权限都绑定在同一个个人账号上，迁移成功也会留下审计和接管风险。更合理的做法是让 CI 只获得完成任务所需的最小权限，发布凭据通过安全变量或受控文件注入，避免出现在仓库、Shell 历史和普通构建日志中。

旧环境清理条件

旧打包机至少要通过以下测试，才适合退租：

  • 新 Mac 从干净目录检出源码；
  • 依赖可以独立解析；
  • Xcode 27 版本和 SDK 与基线一致；
  • Apple Distribution 证书、私钥和 Profile 可以完成目标 Archive；
  • xcarchive、dSYM 和 IPA 已经进入可恢复存储；
  • App Store Connect API 凭据可以完成一次目标上传；
  • 新 Runner 在正式标签下成功执行任务；
  • 旧 Runner 已停止或移除；
  • 旧主机断开后，关键发布流程仍能运行；
  • 临时 Token、共享目录、Shell 历史和日志中的秘密已清理或轮换。

⚠️ 不要在新环境完成真实发布前删除旧钥匙串、撤销唯一证书或清空归档目录。迁移失败时，旧主机就是回退路径；一旦同时删除签名资产和旧环境，恢复成本会迅速上升。

可以用下面的命令检查常见遗留位置，但删除前必须先人工确认：

history | grep -Ei 'token|key|password|auth'
find "$HOME" -maxdepth 4 \
  \( -name "*.p12" -o -name "*.p8" -o -name "*.mobileprovision" \) \
  -print

命令输出只用于定位，不代表可以直接删除。对证书、API 私钥、Runner 配置和构建日志，应先确认新环境已经接管，再进行撤销、轮换或清理。

迁移验收对比表

下表适合在退租前逐项打勾。任何一项处于“仅复制”状态，都不能视为完成。

验收维度 仅复制文件的结果 可恢复迁移的标准 旧环境清理条件
源码与依赖 项目目录存在，但可能缺少锁文件和私有依赖权限 干净检出后可解析依赖并进入目标 Scheme 新环境不读取旧目录
Xcode 27 工具链 安装了 Xcode，但版本和 SDK 未记录 版本、SDK、路径、Scheme 和构建配置与基线一致 完成一次独立 Archive
签名身份 只有 .cer 或 Profile Apple Distribution、匹配私钥和 Profile 可用于目标签名 新环境完成签名验证
发布凭据 环境变量名称存在，私钥可能丢失 Key ID、Issuer ID 与私钥匹配，并可完成上传 旧凭据已停止、撤销或轮换
归档产物 只保存 IPA 或缓存 每个版本可找回 xcarchive、dSYM、UUID 和上传记录 备份可打开、导出或验证
自动化 Runner 新旧节点使用相同标签 新 Runner 完成隔离任务和真实发布任务 旧 Runner 已停止或移除
退租动作 直接删除用户目录 完成断开旧主机后的恢复测试 没有唯一资产遗留在旧主机

迁移方案选择

如果当前打包机已经接近退租时间，选择新环境时不要只看能否打开 Xcode。对独立开发者而言，关键差异在于是否能保留完整 root 权限、是否方便安装 Xcode 27 工具链、是否能让 Runner 长期在线，以及迁移失败时能否继续访问旧环境。

自购 Mac 适合长期稳定重负载、需要物理设备接口或必须把硬件放在办公室的团队。临时本地 Mac 适合一次性发布，但不适合持续运行的打包任务。其他云端方案则可能遇到 macOS 可用性、权限和图形化工具链限制，不能简单等同于一台完整的远程 Mac。

如果当前环境无法稳定保留钥匙串、后台 Runner、归档空间或 Xcode 版本，使用 SFTPMAC 的远程 Mac 方案重新建立迁移目标，通常比在旧主机到期前仓促删除文件更容易控制风险。需要核对预算和租赁周期时，可参考 Mac 远程租赁价格说明，先确认交付方式、访问权限和使用周期，再决定是否并行保留旧节点。

最终建议很明确：先在新远程 Mac 上完成一次不依赖旧主机的真实发布，再处理退租和清理。若当前方案只是临时电脑、无法 7×24 小时在线，或把签名私钥和 Runner 配置分散在个人目录中，那么它的主要缺点不是速度慢，而是发布链路难以接管、故障后难以恢复、退租时容易丢失唯一资产。对需要 Xcode 27 构建、Apple Distribution 签名和常驻自动化任务的开发者，选择可持续访问的 SFTPMAC Mac 环境，会比继续依赖不可审计的旧打包机更稳妥。