GitHub Actions Node 24 迁移：2026 Mac CI 升级清单

最后更新于 2026 年 9 月 2 日，日期与迁移行为核实自 GitHub Node 20 弃用公告、Runner 最低版本执行时间表 及官方 Runner 文档。

截至 2026 年 9 月 2 日，GitHub Actions Node 24 迁移不应等到 Node 20 正式移除后再处理。 企业应立即在不持有生产签名凭证的隔离 Mac 节点上强制启用 Node 24，完成 Action、Runner、macOS 与 Xcode 流水线的双轨验证，再按 Runner Group 或标签分批切换生产节点；无法升级的旧节点，应退出生产池，必要时用新的远程 Mac 节点替代。

这篇文章适合三类团队：管理自托管 Mac Runner 的平台团队、负责 iOS 发布稳定性的研发效能团队，以及需要规划 Mac 替换容量和业务连续性的 IT 负责人。

先锁定 3 个不同的版本边界

迁移前最容易出现的错误，是把“Action 使用的 Node 运行时”“项目安装的 Node.js 版本”和“Actions Runner 应用版本”当成同一件事。它们分别由不同配置控制，修复其中一项，并不能自动解决另外两项。

• JavaScript Action 运行时：由 Action 的运行配置和 GitHub Actions 的迁移策略决定，影响 actions/checkout、缓存、制品上传以及自定义 JavaScript Action。
• 项目 Node.js 版本：由 package.json、锁文件、版本管理工具或工作流中的安装步骤决定，影响前端构建、脚本和依赖安装。
• Runner 应用版本：负责连接 GitHub、接收任务和执行步骤，旧版本可能无法满足 Node 24 或新的最低版本要求。

GitHub 已确认，Runner 从 2026 年 6 月 16 日起逐步默认使用 Node 24；Node 20 的临时回退将持续到 2026 年 9 月 23 日。此外，Node 24 不兼容 macOS 13.4 及更低版本。这些日期和系统条件均应以官方公告为准，而不是以社区帖子或内部旧文档为准。详见 GitHub Node 20 弃用与 Node 24 迁移说明。

这会带来至少 4 个隐性风险：

1. 工作流表面成功，Action 实际仍在旧运行时执行。如果只检查项目的 node --version，可能漏掉 Action 内置运行时。
2. 旧 macOS 节点无法承载 Node 24。这不是简单重装 Runner 就能解决的问题。
3. Runner 升级中断会造成排队或任务重新路由。在线但不符合标签、版本或 Group 条件的节点，不能视为可用容量。
4. 签名节点的权限边界可能被迁移破坏。临时试点若直接复制生产证书、Keychain 或部署凭证，兼容性测试会扩大安全影响。

GitHub 的自托管 Runner 文档说明，Runner 应用必须在主机上运行并保持与 GitHub 的通信，才能接收任务；如果没有匹配的在线空闲节点，任务会继续排队，超过 24 小时仍未执行则会失败。这个排队行为意味着，迁移计划必须包含可用替代节点，而不能只安排一次升级窗口。参考 Self-hosted runners reference。

第一步：在迁移启动日建立资产清单

先不要修改生产工作流。建议以仓库为单位建立一张资产表，至少包含以下字段：

• 仓库名称、工作流文件和生产分支；
• 每个 uses: 引用的 Action 名称、版本或提交 SHA；
• 是否属于 JavaScript Action、Composite Action 或 Docker Action；
• Runner 名称、状态、应用版本、标签和 Runner Group；
• macOS 版本、CPU 架构、Xcode 版本及签名用途；
• 是否访问私有依赖、代理证书、Keychain、缓存目录和制品存储；
• 最近一次成功构建、失败日志和负责人。

Runner 的版本、操作系统、状态和标签可以通过官方 REST API 查询。组织级接口会返回 version、os、status、busy 和 labels 等字段，适合用来生成初始盘点报告。可参考 Self-hosted Runner REST API。

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/orgs/ORG/actions/runners

随后从工作流运行记录和日志中筛选以下信号：

• 使用 Node 20 的弃用告警；
• Action 下载、启动或依赖安装失败；
• Runner 报告版本过旧；
• macos-13 或更低系统节点仍被生产标签引用；
• 自定义 Action 在 require、网络请求、文件权限或子进程调用处出现异常。

工作流运行记录可以通过官方接口查看、重跑、取消和获取日志，因此建议把失败日志纳入迁移证据，而不是依赖开发者口头反馈。相关说明见 Workflow Runs REST API。

✅ 迁移启动检查清单

• [ ] 每个生产仓库都有对应的工作流和 Runner 清单
• [ ] Action 运行时与项目 Node.js 版本已经分栏记录
• [ ] Runner 版本、macOS 版本和 CPU 架构已经核对
• [ ] 旧 Action 的固定版本或提交 SHA 已标记
• [ ] 生产签名节点与普通测试节点已经区分
• [ ] 每条关键流水线都有成功日志和负责人

第二步：在第一小时用隔离节点强制运行 Node 24

试点节点应满足两个条件：一是能够运行真实的 Mac CI 任务，二是即使测试失败，也不会暴露生产签名凭证。对于已有自托管 Mac Runner 的团队，可以新建独立标签，例如 macos-node24-canary，并限制可使用它的仓库或工作流。

GitHub 的官方迁移公告提供了 Node 24 提前测试的环境变量：

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

也可以将变量设置在 Runner 主机环境中，但工作流级别更容易审计和回滚。Node 20 默认回退变量只适合短期应急，不应被写入长期生产模板，因为 GitHub 已明确该回退会在 2026 年 9 月 23 日停止。变量名称、行为和日期应以官方迁移公告为准。

第一条基线流水线不要只执行 xcodebuild。至少应覆盖：

1. 拉取公开和私有依赖；
2. 执行 actions/checkout；
3. 恢复和写入缓存；
4. 运行一个自定义 JavaScript Action；
5. 执行测试与 Xcode 构建；
6. 生成归档文件；
7. 上传制品并校验文件完整性。

这一步的判断标准不是“编译成功一次”，而是每个步骤是否在相同权限、网络、代理和缓存条件下稳定完成。若只验证编译，可能遗漏自定义 Action、缓存插件或制品上传阶段的运行时错误。

Actions Runner 的官方 Releases 页面显示，较新的 Runner 版本已经加入 Node 24 支持和迁移开关，但官方同时说明 Runner 采用渐进式发布策略，某个最新版本不一定已经出现在每个企业、组织或仓库的下载页面。发布前应同时查看 Actions Runner Releases和目标组织的 Runner 下载页面，不能只复制公开 Releases 页面的版本号。

第三步：在首日修复 Action、Runner 和旧 macOS

试点失败后，按影响范围处理，而不是立即把所有节点升级到同一状态。

先升级仍依赖旧运行时的 Action

对于官方或第三方 Action，优先寻找维护者已经发布的 Node 24 兼容版本。固定到旧提交 SHA 的工作流尤其需要人工检查，因为它不会随着维护者移动标签而自动更新。

GitHub 支持使用标签、分支或提交 SHA 指定 Action 版本，并建议第三方 Action 使用 SHA，以降低标签被移动后的供应链风险。迁移时可先在试点分支更新版本，验证后再把经过审核的 SHA 合并到生产分支。

旧版 Action 能否继续运行，不能只看名称或主版本号。需要检查：

• action.yml 中声明的运行时；
• 打包产物是否包含旧版 Node 依赖；
• 是否使用已变化的文件、网络或子进程行为；
• 是否依赖旧 macOS 的系统工具；
• 是否由维护者明确说明支持 Node 24。

再升级 Runner 应用并验证服务恢复

macOS Runner 不仅要显示在线，还必须能在重启后自动回连。macOS 可以通过 svc.sh 安装和管理服务，底层使用 launchd；状态检查不能替代重启后的实际验证。可参考 配置 self-hosted Runner 服务。

./svc.sh status
./svc.sh stop
./svc.sh start

完成 Runner 升级后至少验证 5 项：

• [ ] Runner 在组织页面显示为在线
• [ ] Runner 版本与目标组织下载页面一致
• [ ] 服务重启后仍能注册并监听任务
• [ ] 标签和 Runner Group 没有丢失
• [ ] 任务失败后能够重新路由到保留节点

如果旧 macOS 低于 Node 24 的支持条件，应选择系统升级、节点替换或退出生产池。临时回退变量只能争取迁移窗口，不能把不兼容节点包装成长期生产方案。

第四步：用真实 Xcode 与签名流程完成生产验证

Node 24 迁移直接影响的是 JavaScript Action 运行时，但企业 iOS CI 的风险通常出现在完整交付链路。因此，验证必须包括 Xcode、依赖、测试、归档、签名和制品上传，而不是只运行一个单元测试任务。

推荐将验证分为两层：

普通构建节点

普通构建节点可以验证：

• Xcode 选择和命令行工具路径；
• Swift 或 Objective-C 编译；
• CocoaPods、Swift Package Manager 或私有依赖；
• 单元测试和 UI 测试；
• 缓存恢复、缓存写入和构建产物上传。

受控签名节点

签名发布节点应单独验证：

• 临时 Keychain 是否能正确创建和解锁；
• 证书、描述文件和权限是否匹配；
• codesign、归档和导出是否成功；
• App Store Connect 或内部制品库上传是否完成；
• 任务结束后是否清理临时凭证和工作目录。

GitHub 明确提醒，自托管 Runner 不具备托管 Runner 那种天然的临时、干净虚拟机保证；不可信工作流可能持久化影响 Runner，并接触主机上的密钥或网络资源。对于签名节点，应限制 Runner Group 的仓库范围，并让发布凭证只在经过审批的环境中注入。参考 GitHub Actions 安全使用指南。

这里还要特别检查 3 类不容易被日志直接暴露的问题：

1. 代理证书：Node 24 下的网络请求可能触发证书链、代理变量或 TLS 配置差异。
2. Shell 脚本：脚本中固定的 Node 路径、临时目录和权限假设可能与新 Runner 环境不一致。
3. 缓存目录：缓存命中不代表缓存可复用，必须确认架构、Xcode 版本和依赖锁文件没有被混用。

第五步：在首周建立双轨、回滚与无人值守恢复

生产迁移不建议采用“一次性切换”。保留已验证的生产池，同时建立 Node 24 试点池，再按照仓库风险分批迁移：

• 第一批：测试仓库、非签名构建和低频任务；
• 第二批：普通生产构建和内部发布；
• 第三批：正式签名、商店发布和业务关键流水线。

工作流可以通过标签选择节点，例如：

runs-on: [self-hosted, macOS, arm64, macos-node24-canary]

标签只能表达调度条件，不能替代安全边界。需要结合 Runner Group 限制仓库范围，避免任何能够触发工作流的代码都获得签名节点执行机会。

回滚演练至少覆盖以下故障：

• Node 24 Action 启动失败；
• Runner 自动更新中断；
• macOS 节点重启后服务没有恢复；
• Xcode 构建成功但签名或制品上传失败；
• 试点节点离线后任务无法重新路由；
• 回退后误把已经淘汰的 Node 20 节点重新纳入生产池。

回滚的目标不是恢复所有旧配置，而是恢复“已验证的生产路径”。因此，回退前应保留生产池的 Runner 版本、标签、Group、工作流提交和签名配置快照；回退后则要明确哪些 Action 仍未完成升级，避免形成无人负责的永久例外。

第六步：在截止日期前完成生产准入

截至 2026 年 9 月 2 日，距离 Node 20 临时回退结束的 2026 年 9 月 23 日还有明确的迁移窗口；GitHub Enterprise Cloud 自托管 Runner 最低版本的全面强制执行计划从 2026 年 9 月 25 日开始。GitHub 也说明具体版本和渐进发布状态可能调整，因此企业应在组织下载页面和官方 Changelog 中复核实际要求。

生产准入表建议只允许“通过”“有条件通过”“阻断”三种状态：

两张表确定节点处置与替换优先级

下面这张表用于决定旧 Mac Runner 的去留，不建议只按硬件新旧判断。

容量替换也应按任务类型拆分，而不是简单增加机器数量：

如果现有节点无法按期完成升级，申请隔离的远程 Mac 作为试点，往往比等待唯一生产节点在截止日后集中故障更容易控制风险。RUVCLOUD 提供按周期使用真实 Mac 主机的方案，可先查看 RUVCLOUD 的远程 Mac 服务说明，再依据组织的 Runner、网络和签名策略决定是否纳入替换计划；具体周期与费用应以 RUVCLOUD 当前价格页面为准。

FAQ：企业迁移时最容易误判的 5 个问题

GitHub Actions 移除 Node 20 后，哪些工作流最容易失败？

直接调用仍依赖 Node 20 的 JavaScript Action、固定旧版本 Action 的工作流，以及使用旧 macOS 或旧 Runner 的自托管任务风险最高。单纯在项目中使用 Node 20，并不等于 Action 运行时仍是 Node 20，必须分别检查 action.yml、Runner 版本和工作流日志。

自托管 Mac Runner 怎样测试 Node 24 兼容性？

应选取不持有生产签名凭证的隔离节点，设置官方 Node 24 强制变量，连续执行 checkout、缓存、制品上传、自定义 Action 和完整 Xcode 流水线。通过后还要记录 Runner 重启、服务恢复、私有依赖、Keychain 与签名结果，不能只看一次编译是否成功。

旧版 GitHub Action 还能不能继续在 Node 24 上运行？

不能仅凭版本号判断。若旧 Action 的实现、依赖和打包结果兼容 Node 24，可能继续工作；但固定 Node 20 运行时、使用过时依赖或依赖旧系统行为的 Action 可能失败。企业应优先升级到维护者已声明支持 Node 24 的版本，并保留可审计的提交或版本记录。

Mac Runner 升级失败时，怎样保留生产回退节点？

不要直接覆盖唯一生产节点。应先复制标签和 Runner Group 配置，保留已验证的生产池，同时把 Node 24 试点节点限制到指定仓库；只有核心流水线、签名隔离、重启恢复和制品上传全部通过后，才逐批转移任务。

Node 24 迁移是否必须同时升级 macOS 和 Runner？

不一定需要同日升级，但三者必须作为一个兼容性组合验证。Node 24 对 macOS 13.4 及更低版本不兼容，Runner 也需要满足 GitHub 当前执行要求；如果旧节点无法同时满足条件，应升级系统、替换节点或退出生产池，而不是长期依赖回退变量。

给 IT 负责人的最终处置建议

如果现有方案是把所有工作流绑定在少数旧 Mac 上，主要缺点通常不是“编译速度不够”，而是唯一节点升级会同时影响多个仓库，旧 macOS 可能无法支持 Node 24，签名凭证容易与试点环境混用，而且 Runner 重启或更新失败后缺少可立即接管的备用容量。继续依赖 Node 20 回退变量，只会把风险推迟到更窄的窗口。

完成资产盘点后，如果旧 Mac 无法在 2026 年 9 月 23 日前完成验证，可以先通过 RUVCLOUD 申请隔离的远程 Mac 试点节点，用真实 Xcode、签名和制品流水线确认 Node 24 兼容性，再决定替换数量和租赁周期。对需要临时算力、迁移过渡或业务连续性备用节点的团队，这种双轨方式通常比在唯一生产 Mac 上直接升级更容易回滚，也更便于把采购决策建立在实际验收证据上。