GitHub Actions 自托管 Mac Runner 怎么部署？2026

GitHub 为 Runner 注册流程生成的令牌 1 小时后过期；因此先把主机、仓库范围和依赖准备好，再开始注册。(GitHub 官方添加 Runner 指引)
如果工作流确实需要 macOS，且 Mac 主机能持续联网，就可以把远程 Mac 配成 GitHub Actions 自托管 Runner；先在受控仓库完成注册、服务启动和工作流验收。不要让持久运行的主机执行不可信的外部代码。

独立 iOS／macOS 开发者：希望在 Mac 上运行必须依赖 macOS 的 GitHub Actions 任务。
自由职业者与小型远程团队：需要持续可访问的 macOS 构建环境，也要评估维护责任和仓库权限边界。

部署前判断：工作流是否真的需要 Mac

不要因为项目用了 GitHub Actions，就默认需要 Mac Runner。先检查工作流中的构建、测试或签名步骤：只有必须使用 macOS、Xcode 或其他 Mac 工具的任务，才值得部署 Mac 主机。普通跨平台脚本可继续使用现有 Runner，避免多出一台需要维护的主机。

托管 Runner 与自托管 Runner 的责任边界也不同。托管 Runner 由平台管理运行环境；自托管 Runner 则由你提供并维护主机、操作系统和已安装软件。GitHub 说明，自托管 Runner 的工作环境不保证每次任务都从干净实例开始，主机和其他软件更新也需要使用者负责。(GitHub 自托管 Runner 说明)

项目只需要运行通用脚本，也要部署 Mac Runner 吗？
通常不用。先把不依赖 macOS 的 job 留在现有环境，只把必须运行于 Mac 的步骤单独派发，能减少主机维护范围，也更容易定位失败原因。

注册准备：确定范围、权限和工作目录

先决定 Runner 是绑定单个仓库，还是供组织内多个仓库共用。仓库级 Runner 的可见范围较窄，适合先做试运行；组织级 Runner 便于复用，但也要求更谨慎地限制哪些仓库能调用它。选择范围后，再从 GitHub 对应的仓库或组织设置页面获取注册命令。

开始前逐项确认：

1. 你有权管理所选仓库或组织的 Runner。
2. Mac 能访问 GitHub Actions 所需网络服务，且运行时不会被休眠或断网打断。
3. Runner 有单独的工作目录；项目依赖、证书和缓存不与无关任务混用。
4. 已决定哪些工作流可以访问 Runner，以及任务运行时会接触哪些密钥。
5. 预计执行的工作流确实需要 Mac 环境，而不是仅仅因为项目名称包含 iOS 或 macOS。

GitHub 的 Runner 参考资料列出 macOS 11.0 或更高版本为支持环境，并提醒主机需要能与 GitHub 通信；实际注册时仍应以设置页面显示的系统和架构选项为准。(GitHub 自托管 Runner 系统要求)

GitHub Actions 自托管 Mac Runner 注册

怎么添加 macOS 自托管 Runner？
在选定的仓库或组织设置中进入 Actions 的 Runner 管理页，新增自托管 Runner，选择 macOS 和与主机匹配的架构，然后按页面当前显示的顺序下载、解压并配置 Runner。不要从旧文章复制下载地址或注册命令；GitHub 当前页面才是该次注册的操作依据。

操作顺序如下：

1. 打开目标仓库或组织的 Settings，再进入 Actions 与 Runners。
2. 新增 self-hosted runner，选择 macOS 和正确的处理器架构。
3. 在 Mac 上建立专用目录，按页面给出的命令下载并解压 Runner。
4. 将页面生成的注册命令粘贴到该目录的终端中，完成注册。
5. 返回 Runner 页面，确认新主机出现并显示在线状态。

注册令牌是临时凭据，不要贴到仓库文件、工单或公开聊天中。GitHub 文档说明注册令牌 1 小时后过期；如果命令执行前已经过期，应回到设置页面重新生成，而不是复用旧令牌。

常驻服务：终端关闭后是否继续接单

关闭终端后，Mac Runner 还能接收任务吗？
如果 Runner 只在终端前台运行，关闭该进程后，它就不能继续接单。要让它在退出终端后运行，应按 GitHub 的 macOS 服务流程配置并启动系统服务；主机仍须保持开机、联网，且服务正常运行。(GitHub macOS Runner 服务配置步骤)

在 Runner 安装目录中执行官方服务命令：

./svc.sh install
./svc.sh start
./svc.sh status

检查状态时，不要只看命令是否返回成功。回到 GitHub 的 Runner 页面确认主机在线，再重启 Mac 验证服务是否恢复。GitHub 的监控说明提到，macOS 服务可通过 svc.sh status 或 launchctl 查看；Runner 页面则会列出在线状态。(GitHub Runner 监控与故障排查说明)

示例输出：

status actions.runner.example.runner01:
.../Library/LaunchAgents/actions.runner.example.runner01.plist
Started:
... actions.runner.example.runner01

如果显示离线，排查顺序建议是：主机是否开机、网络是否可用、服务是否启动、Runner 是否能访问 GitHub。GitHub 页面上的状态可区分 Idle（在线空闲）、Active（正在执行任务）和 Offline（未连接）。

工作流验收：标签派发与端到端测试

给 Runner 配置与用途相符的标签，再让工作流明确要求这些标签。GitHub 会根据 runs-on 中的标签寻找匹配主机；自托管 Runner 的默认标签通常包括 self-hosted，多个标签同时指定时，Runner 必须匹配全部标签。(GitHub 自托管 Runner 标签说明)

jobs:
  mac-check:
    runs-on: [self-hosted, macOS]
    steps:
      - uses: actions/checkout@v4
      - name: 确认运行环境
        run: |
          sw_vers
          uname -m

示例中的 macOS 标签必须确实存在于你的 Runner 上；标签是派发条件，不是平台对实际硬件或系统的独立验证。首次测试先使用低风险、可重复的任务，确认作业被派发、日志可查看、结果能交付。随后再运行项目真正依赖的 macOS 工具，并检查产物、签名或测试结果。一次成功只说明这组配置和任务通过，不代表所有项目都兼容。

安全与维护：持久主机的边界

公开仓库的外部 Pull Request 能交给自托管 Mac Runner 吗？
不建议把持久的自托管主机交给不可信的外部代码。GitHub 明确提醒，公开仓库的外部 Pull Request 可能执行危险代码并危及 Runner 主机；即便是私有或内部仓库，也要审查哪些人能提交或触发工作流，以及任务可访问的密钥和 GITHUB_TOKEN 权限。(GitHub 安全使用说明)

部署后还要把维护纳入日常流程：检查 Runner 状态和 _diag 日志；分别管理 macOS、项目依赖和 Runner 应用更新；限制可调用该主机的仓库，并避免让不同信任级别的任务共用带有敏感数据的工作环境。GitHub 的安全说明特别指出，自托管 Runner 不具备托管 Runner 那种干净、临时的隔离环境保障。

下面两张表用于在实施前确定责任范围，并在上线前留下可复核的验收记录。

若你当前依赖本地 Mac，常见限制是主机随人移动、断电或断网会中断任务，还要自行处理系统更新与服务状态。把工作环境迁到远程 Mac，可以减少携带实体主机的需要，但网络连接、权限、使用周期和重启后的服务状态仍须逐项核实。若需要临时或阶段性的 macOS 自动化环境，可查看 OnceMac 的方案对比，再核对 数据中心相关信息 与实际工作流条件；确认适配后再考虑租赁 OnceMac 的 Mac。若团队依赖长期稳定的专用硬件、特殊物理接口或高强度持续任务，自行维护主机可能更合适。对访问方式或权限边界有疑问时，可先通过 OnceMac 联系页面核实，不要仅凭本文示例判断环境适配性。