症状 → 作业仍引用 macos-14,无法分配 Runner;或换标签后构建、测试、签名失败。
最快解法 → 改用当前受支持且符合项目架构要求的 Runner,再分别验收 Xcode、测试和签名发布;改标签不等于 CI 已迁移完成。
适合正在处理退役后 iOS/macOS CI 故障的企业 IT 负责人、平台工程师和发布负责人:你需要确认影响范围、定位失败阶段,并拿到足以支撑恢复放行的作业证据。
最后更新于 2026 年 11 月 15 日;核实自 GitHub 的 macOS-14 Runner 退役公告及官方 Runner 镜像清单。
SECTION 01Runner 未接单:先核对标签与队列
故障信号:作业待处理、没有 Runner 接单,或日志显示无法匹配可用 Runner。先看工作流中的 runs-on,确认它是否仍包含已退役标签;截至本文核验日,GitHub 已于 2026 年 11 月 2 日退役 macos-14、macos-14-large 和 macos-14-xlarge,具体日期和受影响标签见官方退役公告。
不要仅凭截图把所有排队问题都归因于镜像退役。检查作业所在分支实际采用的工作流文件、运行记录中的队列状态,以及组织或仓库的 Runner 组配置;如果 runs-on 已改正但仍未分配,再按GitHub 工作流排障文档检查 Runner 选择与其他调度问题。
先选择与项目条件相符的目标,再进入工具链验收。下表用于初步筛选;标签、架构和镜像内容可能变化,应用前要重新对照官方 Runner 镜像清单。
| 选择 | 适用条件 | 主要核验点 |
|---|---|---|
macos-15 |
项目依赖已在该标签对应的 Apple Silicon 架构上验证 | 运行时实际架构、Xcode、SDK 与模拟器运行时 |
macos-15-intel |
必须运行 Intel 架构任务,且该标签符合团队的托管 Runner 需求 | Intel 二进制、依赖安装与构建结果 |
macos-26 |
项目已验证可运行于较新的 macOS 镜像 | 操作系统差异、默认工具链及应用兼容性 |
| 自管 Mac Runner | 有托管镜像不能满足的必要条件,且团队能承担主机运维 | 身份隔离、补丁、网络、凭证及可用性责任 |
SECTION 02架构与依赖不兼容:分清标签和二进制问题
换成新标签后,Runner 能启动却在安装依赖或链接阶段报错,不能据此断定是镜像调度故障。先在实际失败作业记录 RUNNER_ARCH 或 ${{ runner.arch }},再检查依赖安装日志、二进制格式和项目中的架构判断逻辑;Runner 上下文说明列出了当前作业的操作系统与架构信息。
例如,某个项目迁移标签后,依赖安装通过,但链接步骤因架构不匹配失败。这时应先定位具体不兼容的预编译库或脚本分支,确认项目是否能用匹配架构的依赖重新构建,再决定目标 Runner;更换系统镜像不会自动把 Intel 专用工具迁移为 Apple Silicon 版本。
✅ 继续用托管 Runner:依赖支持选定架构,且真实构建与测试通过。
⚠️ 考虑不同标签或自管节点:必要依赖只能运行于特定架构,而当前可用托管镜像无法满足。
SECTION 03Xcode 与 SDK 发生变化:在作业内确认实际选择
标签表示 Runner 镜像,不等于固定的 Xcode 版本。应从失败作业日志读取 xcode-select -p、xcodebuild -version 和目标 SDK 版本;必要时再检查所需模拟器运行时。把这些信息与macOS-15 镜像的软件清单逐项对照,确认目标工具确实存在。
建议把诊断步骤放进真实构建 job,而不是只在另一个 job 里采样:
- name: 记录 Runner 与 Xcode 环境
run: |
echo "arch=$RUNNER_ARCH os=$RUNNER_OS"
sw_vers
xcode-select -p
xcodebuild -version
xcrun --sdk iphoneos --show-sdk-version
xcrun simctl list runtimes
如果实际选择的 Xcode 与项目要求不一致,先显式选择镜像中存在的版本,再重跑同一提交。Apple 说明 Xcode 自带 xcodebuild、xcrun 等命令行工具;仅有 Command Line Tools 并不能替代完整 Xcode,相关边界可对照 Apple 的命令行工具说明。
SECTION 04编译通过但测试或产物不通过:按阶段留下证据
构建成功只是一个阶段的结果,不是发布链路恢复的证明。将同一提交依次复验编译、单元测试、模拟器测试、归档与产物检查;记录每阶段的退出状态、所用 Xcode/SDK、目标设备及产物校验信息,定位失败首次出现的位置。
实际排查按以下步骤执行:
- 圈定影响范围:记录仓库、分支、提交、作业名、失败步骤和 Runner 标签,判断是否所有工作流都受影响。
- 修正标签:将退役标签替换为受支持且符合项目架构要求的标签;保留改动前后的工作流版本,避免无法回溯。
- 采集环境:在构建 job 输出 Runner 架构、系统版本、Xcode 路径与版本、SDK 和模拟器运行时。
- 重跑同一提交:先完成编译与单元测试,再运行模拟器测试;每一阶段分别保存日志,避免一次绿色结果掩盖未执行的门禁。
- 核对产物:检查归档是否生成、目标平台与构建设置是否符合发布要求,并确认产物来自待验收的提交。
- 重新验证发布:在受控流程中运行签名和发布验证,通过后再放行;把工作流、日志与产物对应起来,作为恢复记录。
若编译成功而模拟器测试失败,先检查运行时和项目对环境变量的假设;若测试通过但归档异常,则回看归档配置和产物检查。不要把镜像更新与应用代码缺陷混为一类,也不要在没有同提交证据时宣布修复完成。
SECTION 05签名与发布失败:单独检查凭证链路
签名报错可能与 Runner 环境变化同时出现,但不能仅凭发生时间判定是退役直接造成。独立核对签名身份、描述文件、Keychain 初始化、工作流所需凭证和权限是否在替代环境可用;日志不要输出私钥、证书密码或未脱敏的秘密值。
把签名验收和构建验收分开:验证实际用于归档的身份、签名结果和发布步骤所需权限,并保留受限访问的日志及产物记录。单次构建成功不代表签名已通过,更不能证明发布链路已恢复;应在发布负责人批准后,按团队的发布门禁完成验证。
SECTION 06托管 Runner 与自管 Mac:按必要条件决定承载
只有真实工作流证据表明托管镜像不能满足项目条件,才有必要比较自管或远程 Mac。GitHub 的自管 Runner 工作流说明介绍了用 Runner 标签路由作业的方式;采用自管方案意味着团队还需负责主机、更新、权限与凭证治理。
✅ 优先托管 Runner:团队不需要固定主机状态,任务能适配现有镜像,且网络和工具链条件均已通过实测。
⚠️ 评估自管或远程 Mac:必须锁定特定架构、工具链或网络访问条件,且替代托管镜像确实无法满足。评估时把容量、环境隔离、补丁、凭证保管和故障恢复责任列清楚,不要把“需要更可控”当成免除运维的理由。
完成故障定位后,再根据真实工作负载比较当前托管 Runner 与远程 Mac:前者的环境和架构选择可能不符合特定依赖,镜像预装工具会变化,私网和凭证条件也需要单独核验;远程 Mac 则需要你确认所需配置、访问交付方式和租用周期是否适合团队。若只是临时验证迁移、补充测试或短期承载构建,可以先查看 MACNOX 的远程 Mac 方案及实际公开的租用周期和计费信息,以页面披露内容判断是否适配;若需要长期、稳定的专用重负载环境,或必须连接物理设备,应把自购或自管方案一并评估,而不是默认租赁更合适。
SECTION 07常见问题 FAQ
macOS-14 退役后为什么工作流没有 Runner 接单?
先确认 runs-on 中是否还留有已退役的 macos-14 系列标签,并检查实际运行记录的队列状态。若配置已更新,继续核对 Runner 组与调度条件;不要把所有“没有接单”都直接归因于镜像退役。
macOS-14 换成 macOS-15 后,iOS 构建失败怎么办?
先在失败作业中记录实际架构,再查依赖安装和链接日志;随后确认 Xcode、SDK、模拟器运行时与项目要求一致。这样能区分架构不兼容、工具链选择变化与应用代码问题,避免盲目换标签。
更换 macOS Runner 后,如何确认实际使用的 Xcode?
在实际构建 job 中输出 xcode-select -p、xcodebuild -version 和目标 SDK 版本,并将结果与对应镜像清单比对。若需指定 Xcode,还要在同一工作流的真实构建任务里验证选择生效。
什么时候应该改用自管 Mac Runner?
当日志证明必需的架构、工具链或网络条件无法由可用托管镜像满足时,再评估自管 Mac Runner 或远程 Mac。将维护、补丁、凭证、隔离和恢复责任纳入决策;若托管环境能通过配置和验收满足要求,不必仅因一次失败就迁移承载方式。
SECTION 08常见问题 FAQ
macOS-14 退役后工作流为什么一直没有 Runner 接单?
先检查待运行作业的 runs-on 是否仍包含 macos-14、macos-14-large 或 macos-14-xlarge,再查看该次运行的队列状态与工作流实际分支。GitHub 已于 2026 年 11 月 2 日退役这些标签;若配置已更新仍排队,再检查组织 Runner 组、并发限制和其他调度条件,不要只根据报错截图下结论。
把 macOS-14 改成 macOS-15 后,iOS 构建报错该从哪里查起?
先在构建日志记录 Runner 架构,再核实项目依赖的二进制是否支持该架构;随后明确选择 Xcode,并检查所需 SDK 与模拟器运行时是否实际安装。若依赖日志在编译前就显示架构不匹配,优先处理依赖;若编译成功而测试失败,则继续比较运行时与项目假设。换系统镜像不会自动迁移 Intel 专用依赖。
更换 GitHub Actions macOS Runner 后,在哪里确认实际使用的 Xcode?
不要只看 runs-on 标签。把 xcode-select -p、xcodebuild -version、xcrun --sdk iphoneos --show-sdk-version 和目标模拟器运行时检查加入诊断步骤,并保留对应作业日志;再对照官方 Runner 镜像清单确认该镜像装有什么。显式选择 Xcode 路径后,也要在实际构建作业中验证,不要以单独的诊断作业代替。
macOS-14 退役后,什么情况下该考虑自管 Mac Runner?
先证明替代托管镜像不能满足某项必要条件,例如目标架构、指定工具链、私网依赖访问或签名控制;证据应来自真实工作流日志和失败产物,而不是偏好。若条件可通过受支持镜像和工作流调整满足,继续使用托管 Runner 通常更省去主机维护;确需固定环境或网络控制时,再评估自管或远程 Mac 的隔离、补丁、凭证与运维责任。