GitHub Actions macOS Runner 离线怎么办?2026 排障指南

GitHub Actions macOS Runner 离线怎么办?2026 排障指南

GitHub 官方说明:任务分配给 Runner 后,Runner 若在 60 秒内没有接手,任务会重新排队;这不等于 Runner 已离线。自托管 Runner 路由规则 因此,本周先记录任务状态和最近一次成功运行,再按“Runner 离线、在线但无匹配执行节点、任务已启动后失败”分流排查。标签或 Runner 组不匹配,先修配置;只有主机不可用、网络不稳定或维护能力不足时,才评估更换运行方式。

适合维护 GitHub Actions macOS 自托管 Runner、需要定位服务和连接问题的工程师。
如果 iOS 构建持续排队,可核对工作流标签与 Runner 状态是否对应。
如果你负责团队构建节点,可据故障根因决定修配置还是调整主机方案。

离线状态与排队任务:先分清症状

GitHub 将 Runner 状态显示为“离线”,表示它没有连接到 GitHub;可能原因包括主机关闭、Runner 应用未运行或应用无法通信。官方状态定义与排障入口 与此不同,任务排队可能只是当前没有满足 runs-on 条件的在线空闲 Runner。任务开始后再失败,则应从工作流步骤和 Runner 日志判断,不要仅凭失败结果重启主机。

先在仓库或组织的 Runner 设置页记下状态、标签和 Runner 组,再打开失败或排队的工作流,确认任务停在分配前、接手阶段,还是某个构建步骤。把这些现象与最近一次成功运行的时间、使用的工作流版本放在一起,才能避免把“排队”和“离线”当成同一种故障。

macOS Runner 排障:主机、网络与服务对照

建议按“机器是否可用 → Runner 进程是否运行 → GitHub 连接是否正常”的顺序检查。手动在终端启动 Runner 后能上线,只能说明交互式启动路径可用;它不能证明重启后 launchd 会按预期拉起服务。

观察到的现象 优先检查 判断方向
设置页显示离线 主机供电与联网、Runner 进程、连接检查 先确定是主机停机、服务停止还是出站连接失败
Runner 在线但任务排队 runs-on 标签、Runner 标签、Runner 组权限 全部匹配且有在线空闲节点,任务才有机会被分配
任务已接手后失败 工作流步骤、Runner 的 Worker_ 日志 区分构建脚本或环境错误与 Runner 接单故障
重启后反复离线 svc.sh 状态、服务配置文件、启动账户 检查服务启动是否稳定,而不只看手动启动结果

网络检查与 Runner 诊断日志

在 Runner 安装目录执行官方连通性检查:

./config.sh --check --url https://github.com/ORG/REPO --pat YOUR_TOKEN

把 ORG/REPO 和令牌替换为实际值。该检查会逐项测试所需服务,并在终端报告通过或失败;失败项目的详细信息可从安装目录下的 _diag 日志中查找。GitHub 网络检查与日志说明

如果输出指向网络,继续核对防火墙、代理、DNS 解析以及到 GitHub 所需服务的出站 HTTPS 连接。GitHub 列出了 Runner 通信所需的域名和端口要求,实际放行范围还要结合你的工作流是否下载 Actions、使用制品或访问包服务来确认。自托管 Runner 通信要求 不要把关闭 TLS 证书校验当作常规修复;这会削弱连接验证,不能替代对代理证书或网络策略的正确排查。

网络日志只说明 Runner 到 GitHub 的通信情况,不一定能解释构建脚本为何失败。若任务已经开始,在工作流运行页面打开失败步骤;需要更多 Runner 层信息时,可启用 ACTIONS_RUNNER_DEBUG,然后下载运行日志中的诊断文件。Runner 诊断日志开启方法 工作流日志可显示任务在哪个步骤停止;本机 _diag 中以 Runner_ 开头的日志偏向 Runner 进程,以 Worker_ 开头的日志则对应具体任务。工作流运行日志查看方法

launchd Runner 服务与终端运行

检查 macOS 服务时,先进入 Runner 安装目录查看状态:

./svc.sh status
cat .service

svc.sh status 会通过 launchctl 检查服务;.service 文件可帮助你找到服务的配置路径。若服务状态没有显示运行,或服务在重启后没有恢复,继续核对服务安装情况、启动账户和相关日志。GitHub 的 macOS 排障文档也建议使用 launchctl 观察服务活动,并从 Runner 目录的服务文件确认服务名称。macOS launchd 排查说明

需要留意服务启动时使用的账户和你平时登录终端的账户可能不同。因此,交互式启动成功不能证明服务具备相同的环境变量、目录权限或工具路径。GitHub 文档说明,服务模式用于在机器启动时自动运行 Runner;若你使用自定义服务配置,应确保服务通过官方要求的入口启动。Runner 服务配置说明

在线但无人接单:标签与 Runner 组必须同时匹配

macOS Runner 在线但任务仍排队

检查工作流里的 runs-on,再与仓库或组织设置页展示的 Runner 标签逐项对照。多个标签是累积条件:任务要求 self-hosted、macOS 和某个自定义标签时,Runner 必须具备全部要求;如果还指定了 Runner 组,该组也必须允许此仓库使用。工作流标签与 Runner 组路由规则

例如,工作流要求一个自定义标签,但 Runner 上该标签已被删除,即使 Runner 显示在线,也无法接下这个任务。反过来,如果你误把架构或系统标签写进 runs-on,同样可能没有任何节点满足条件。修改前先从当前仓库的 Runner 页面复制实际标签,不要凭记忆重建配置;再确认 Runner 组是否授权该仓库访问。Runner 组访问权限说明

你可以先勾选核验这些项目,再决定是否重启服务:

如果只是标签或组权限不匹配,优先改正工作流或权限,不要迁移主机。任务路由依据当前仓库或组织的实际设置;重启一台标签仍不匹配的机器,并不会让任务自动找到它。

从配置修复到主机调整:按根因做决定

用下面的评分判断问题落在哪一层。评分描述的是排障优先级,不是 Runner 性能测试结果。

如果这些排查仍无法定位,建议按故障发生顺序保存工作流日志、_diag 相关文件、服务状态和网络检查结果;避免只保留一张“Runner 离线”的截图。把 Runner 的接单记录与失败步骤对齐,通常比反复重启更能区分连接故障和项目错误。

自管 Mac 的优势是你能直接维护硬件与系统环境,但主机断电或本地网络中断会让节点失联;服务配置、系统更新和日志留存也需要团队持续负责。远程 Mac 可以把持续在线的主机环境交由服务方案提供,但不能替你修复错误的标签、权限或 YAML。若根因确实是主机持续在线或运维能力不足,可先查看 VPSPull 的远程 Mac 环境说明 与 远程 Mac 连接选项,再按任务运行方式和团队维护能力评估是否迁移;如果问题只是工作流配置,先改配置才是更直接的修复。

Runner 离线反复排查?用 VPSPull 验证稳定的 macOS 构建环境

VPSPull 提供独享 Apple Silicon 物理机,Pull M4 Pro 配备 64GB 内存和 2TB SSD,适合自托管 CI 与并行测试。