GitHub Actions macOS Runner 任务排队怎么办？2026 自托管验收清单

工作流一直显示“排队中”，Runner 却看起来在线？

最快解法：先保存工作流运行标识与日志，核对 runs-on 标签、Runner 状态和仓库权限；只有证实问题来自可控的 Runner 供给不足，或团队确实需要固定的 macOS 维护环境，再评估自托管。上线前用真实工作流验收接单、构建、清理和恢复，别把“机器已启动”当作故障已解决。

维护 GitHub Actions 流水线的开发者，可以据此判断任务为什么没有被 Runner 接走。
需要固定 macOS 构建环境的小团队，可以用清单逐项验收。
负责 Runner 生命周期的运维人员，可以把恢复与告警测试一并纳入上线流程。

GitHub Actions macOS Runner 排队：先分清未分配、未接单和已启动失败

“排队”描述的是作业状态，不是故障原因。排查前记下工作流运行标识、作业名称、触发方式和最近一次状态变化；随后按下面的表现分流：

• 作业仍在等待，日志没有构建步骤：优先检查有没有符合条件的 Runner，以及它是否被允许接收该仓库的任务。
• Runner 接到分配但没有开始执行：核实机器与 Runner 应用进程是否还在线，检查网络连接和服务日志。
• 作业已经进入运行状态，之后报错：这是构建或步骤故障，不应直接归因于 Runner 数量不足。

GitHub 的自托管路由要求 Runner 同时匹配作业指定的标签与组；没有可用的匹配 Runner 时，作业会留在队列中。GitHub 文档还说明，若已分配的 Runner 在 60 秒内没有接手，该作业会重新排队；持续排队超过 24 小时会失败。这些是官方调度规则，不是判断某个工作流实际排队原因的替代品。请结合自托管 Runner 的路由与支持要求及运行日志判断。

标签和权限都正确，才算找到了可接单的 Runner

先对照工作流中的 runs-on 与 GitHub 设置页上的 Runner 标签。多个标签是同时匹配条件，不是满足其中一个就能接单；自定义标签名称即使看起来像操作系统或架构，也不自动证明机器具备对应能力。标签大小写不敏感，但拼写、组名称和访问范围仍需核实。可参考自托管 Runner 标签路由说明和在工作流中选择 Runner 的规则。

name: macOS runner acceptance

on:
  workflow_dispatch:

jobs:
  runner-check:
    runs-on: [self-hosted, macOS]
    steps:
      - name: Confirm runner can accept a job
        run: |
          echo "Runner accepted the job"
          uname -a

把示例中的标签改成你实际配置的标签，再从目标仓库手动触发。若这份最小工作流仍不运行，就先查路由和访问策略，不要先加机器。组织级 Runner 组可以限制哪些仓库能使用；仓库没获准访问时，机器启动正常也无济于事。尤其是公开仓库，GitHub 提醒自托管 Runner 可能受到来自分支或拉取请求工作流的危险代码影响，配置组权限时应一并考虑隔离策略。详见Runner 组访问策略与安全提醒。

✅ 清点 runs-on 中的每个标签，并逐一与目标 Runner 标签比对。
✅ 检查作业指定的 Runner 组，以及仓库是否在该组许可范围内。
✅ 确认 Runner 位于预期的仓库、组织或企业范围。
✅ 用最小工作流验证接单，再运行实际构建工作流。

Runner 在线与 Runner 可用，是两种不同的判断

Runner 页面显示在线，只能说明它与 GitHub Actions 保持连接；它仍可能因为当前忙碌、任务路由不符或实际服务进程异常而无法处理这个作业。反过来，显示离线也未必代表主机已关机：Runner 应用没有运行，或主机无法与服务通信，都可能造成离线状态。

在 macOS 主机上，检查 Runner 应用进程、网络访问和作为服务运行的状态。重启机器后再确认服务会自动恢复；安排一次短时断网测试，观察 Runner 是否按预期离线、网络恢复后是否重新连接，以及告警能否送达。GitHub 提供 Runner 网络检查方式 config.sh --check，并说明 macOS 服务可用 launchctl 和 svc.sh status 检查；相关操作见自托管 Runner 监控与故障排查。

官方支持范围也要与团队实际需要分开核验：GitHub 当前文档列出 macOS 11.0 及更高版本；x64 受支持，macOS 的 ARM64 标为公开预览。不要只凭机器写着“Mac”就推断它满足某个 Xcode、模拟器或架构要求。Apple 会针对不同 Xcode 版本列出受支持的 macOS 版本；选定构建工具链后，按Apple 的 Xcode 系统要求逐项核对。

提醒：若工作流依赖容器操作或服务容器，GitHub 的自托管 Runner 文档要求使用装有 Docker 的 Linux 机器。不要把这类工作负载误判成 macOS Runner 排队后，继续尝试给 Mac Runner 添标签或加资源。

作业已启动却失败：把构建问题从调度问题中拆出来

看到作业开始运行，就说明至少有 Runner 接到任务。此时先找首个失败步骤，再看错误属于哪一层：

• 工具链不符：核对 Xcode、命令行工具、SDK 与项目要求是否一致。迁移环境后，不要默认系统预装版本等同于旧机器。
• 依赖不可达：确认依赖仓库、包源和构建产物存储位置能从 Runner 主机访问。网络策略变更也可能让构建卡在拉取依赖，而不是卡在接单。
• 签名或密钥问题：检查证书、配置文件、密钥权限和密钥注入步骤是否有效。不要为了定位问题把敏感内容写入普通日志。
• 作业资源不足：查看构建期间的系统日志与资源表现；只有证据指向并发供给或资源瓶颈时，才评估扩容。

需要更多 Runner 执行细节时，可以临时启用 ACTIONS_RUNNER_DEBUG，并在排障后按团队规则撤销或关闭调试设置。官方说明诊断日志包含 Runner 和作业执行过程；可参照GitHub Actions 调试日志设置。把结果分别记录为“未分配”“Runner 未接单”或“构建失败”，避免为了修复工具链错误而盲目添置 Runner。

常见疑问：在线为何不等于接单，迁移后还要查什么？

在线的 Runner 为什么接不到工作流？回到标签、组权限和空闲状态逐项核验。一个作业若指定了多项标签，Runner 必须同时满足；有组织级访问策略时，还要确认目标仓库获得许可。

自托管 macOS Runner 怎样才算通过接单测试？用手动触发的最小工作流指定实际标签，看到作业开始执行并成功结束，再保存运行标识与 Runner 诊断日志。单看主机启动或 Runner 注册页面不足以证明它能接任务。

迁移后工作流运行了，是否可以直接切换？还不够。需要实际验证目标 Xcode 与依赖、签名材料的权限、构建产物，以及失败告警；运行结束后再检查工作目录、临时文件和凭据是否按设计处理。

Runner 页面显示在线但作业没有运行，应该先扩容吗？先核查 runs-on、Runner 组和仓库访问范围，再查看 Runner 是否正被其他作业占用。如果日志显示步骤已启动，则转为构建排错。只有这些条件都通过、且证据显示可用 Runner 供给不足时，新增容量才是有依据的选择。

第一步：用五项清单完成自托管 macOS Runner 验收

按顺序勾选。任何一项失败，都先修复该项并重跑对应工作流，不要把全部故障统一归结为“Runner 不够”。

• [ ] 可接单：目标仓库的最小测试工作流能通过预期标签和组分配到 Runner。
• [ ] 可构建：真实项目能调用要求的 Xcode、依赖和签名流程；成功产物可核对。
• [ ] 失败可告警：人为制造可控的失败或短暂不可用，确认团队能收到告警，并能从运行标识找到诊断日志。
• [ ] 重启可恢复：重启主机后确认 Runner 服务自动启动；模拟网络短时中断，再验证连接恢复和状态回报。
• [ ] 任务结束可清理：检查工作目录、临时文件、日志与凭据处理；确认跨工作流的缓存策略不会把敏感文件带入后续任务。

GitHub 建议对需要自动伸缩的自托管 Runner 采用临时 Runner，而不是持久 Runner；临时 Runner 每次只处理一个作业，注销后仍需由你管理环境清理，并应把诊断日志转存到外部位置。它不等于“任务结束后所有文件自动安全擦除”。涉及不可信代码时，先审查 GitHub 关于自托管 Runner 的安全使用说明，再决定是否复用硬件、缓存或工作目录。

决策条件：该自托管，还是先修配置？

• 若标签或组权限不匹配：先修正工作流与访问策略，再重跑最小测试；新增机器不会改变路由规则。
• 若 Runner 离线或服务重启后不恢复：先修复服务、网络与告警，再做重启验收；未解决生命周期问题前扩容只会增加运维对象。
• 若作业已启动，失败来自工具链、依赖或签名：先恢复构建环境和秘密信息配置；不要把构建错误登记为排队故障。
• 若验收全通过，但高峰时仍缺少符合要求的空闲 Runner，或确实需要固定 macOS 环境：评估自托管供给，并明确维护责任、日志留存和清理机制。
• 若任务主要依赖容器／服务容器，或团队无法承担主机补丁、密钥隔离和故障恢复：回退到更适合该工作流的平台或托管方式，别因“自托管可控”就强行迁移。

从临时排障转向稳定运行：先核对环境，再决定迁移

如果你目前依赖共享或临时 Runner，可能会遇到环境版本不可控、网络访问受限、任务结束后状态难复现等问题；改成自托管则会带来主机更新、权限隔离、日志保留和凭据清理等持续责任。只有需要固定 macOS 工具链、能安排维护责任，且以上验收项都通过时，才值得把工作流迁过去。

如果你需要的是临时构建或迁移验证环境，可以先查看 Hashvps 的环境与套餐说明，核对实际交付环境、Runner 接入方式及工作流要求是否匹配；具体能力以页面可确认的信息为准。若只是标签或权限配置错误，先修配置比换环境更直接。你也可以通过 Hashvps 帮助中心确认接入问题；若工作流要求与可用环境不符，就保留现有方案并修复流水线，而不是为了排队现象仓促迁移。