没有 Mac 也能跑 iOS CI/CD：GitHub Actions 自托管 Runner 接线指南

为什么自托管 Runner 比 GitHub 托管 Runner 更适合 iOS 构建？

GitHub Actions 提供的 macOS 托管 Runner 理论上免去了硬件维护，但实际生产中会碰到几个难以回避的问题。

首先是等待时间。GitHub 的 macOS Runner 池容量远小于 Linux，高峰时段（UTC 12:00–20:00，对应亚太工作时间）从 runs-on: macos-latest 触发到 Runner 就绪，排队时长中位数在 8–15 分钟，偶尔超过 20 分钟。对于一个 Clean Build 本身只需 6 分钟的中型 SwiftUI 项目来说，等待时间已经超过实际编译时间。

其次是Xcode 版本不可控。macos-latest 标签会随 GitHub 基础设施升级静默切换 Xcode 版本，历史上曾出现 Xcode 15 → 16 的无通知升级导致项目构建失败，需要手动追加 xcode-select 步骤并等待大版本兼容。

第三是免费额度消耗快。macOS Runner 的计费权重是 Linux 的 10 倍（GitHub 官方文档），免费账户每月 2000 分钟额度在 macOS 上折算仅 200 分钟，稍微密集一点的迭代周期就会超额计费。

相比之下，自托管 Runner 接在你自己的 Mac 上可以彻底规避以上三点：Runner 永远在线、Xcode 版本由你维护、运行时间不计费。唯一的门槛是你需要有一台持续运行的 macOS 机器——这正是本文要解决的问题。

准备工作：开通云端 Mac 节点与基础环境

在任何 iOS CI/CD 接线之前，你需要一台能 SSH 进去、24 小时在线的 macOS 机器。本文以 VPSRox 独享 Mac mini M4 节点为例（也适用于物理 Mac mini / Mac Studio），以下步骤在 VPSRox 控制台交付后 5 分钟内均可完成。

SSH 接入与 Xcode Command Line Tools

1. 01
   配置 SSH 密钥认证

   在控制台复制公网 IP，本地执行：

   ssh-copy-id -i ~/.ssh/id_ed25519.pub user@<节点IP>

   完成后禁用密码登录（PasswordAuthentication no），防止暴力破解。

2. 02
   安装 Xcode Command Line Tools

   xcode-select --install

   如需完整 Xcode GUI（用于 Archive 签名），从 developer.apple.com/downloads 下载 .xip 文件，解压后移动到 /Applications/ 并切换路径：

   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

3. 03
   安装 Homebrew

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   安装完成后根据提示将 /opt/homebrew/bin 加入 PATH，写入 ~/.zprofile。

4. 04
   验证 Xcode 构建链

   xcodebuild -version

   确认输出 Xcode 版本号与 Build Version，后续 YAML 中可用 XCODE_VERSION 环境变量锁定版本。

安装与注册 GitHub Actions 自托管 Runner

GitHub 提供的自托管 Runner 安装包会在 Mac 上运行一个轮询守护进程，当有 workflow 触发时拉取 job 到本地执行，整个过程无需 Mac 向外开放端口。

在 GitHub 仓库获取注册令牌

进入目标仓库 → Settings → Actions → Runners → New self-hosted runner，选择 macOS 平台，复制页面给出的下载命令与注册令牌（Token 有效期 1 小时）。

1. 01
   下载并解压 Runner

   mkdir actions-runner && cd actions-runner

   curl -o actions-runner-osx-arm64-2.319.1.tar.gz -L https://github.com/actions/runner/releases/download/v2.319.1/actions-runner-osx-arm64-2.319.1.tar.gz

   tar xzf ./actions-runner-osx-arm64-2.319.1.tar.gz

   注意选择 osx-arm64 包（Apple Silicon），版本号以 GitHub 页面显示为准。

2. 02
   注册 Runner

   ./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token <TOKEN> --name mac-m4-vpsrox --labels mac,xcode16,ios

   --labels 自定义标签稍后在 YAML 的 runs-on 中使用，可以精确路由到这台机器。

3. 03
   安装为 launchd 服务（开机自启）

   ./svc.sh install

   ./svc.sh start

   launchd 会在用户登录后自动拉起 Runner 进程。查看状态：./svc.sh status。

在 Workflow YAML 中指向自托管 Runner

注册完成后，在 .github/workflows/ios-ci.yml 里把 runs-on 替换为你的自定义标签：

jobs:
  build:
    runs-on: [self-hosted, mac, xcode16]
    steps:
      - uses: actions/checkout@v4
      - name: Show Xcode version
        run: xcodebuild -version

配置 Xcode 构建环境与依赖管理

一次干净的 iOS 构建通常需要解决三件事：依赖拉取、编译缓存、派生数据路径隔离。

CocoaPods vs Swift Package Manager

如果项目使用 CocoaPods，在 Runner 机器上安装一次即可：

sudo gem install cocoapods

在 CI 步骤中：

- name: Install CocoaPods
  run: pod install --repo-update
  working-directory: ./ios

使用 Swift Package Manager 时，Xcode 会在首次构建时自动解析依赖。为加快后续 CI 速度，可以在 job 中缓存 SPM 解析结果：

- uses: actions/cache@v4
  with:
    path: ~/Library/Developer/Xcode/DerivedData
    key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}

派生数据路径隔离

同一台 Runner 上如果有多个项目并发构建，默认的 DerivedData 路径会相互干扰。推荐在 xcodebuild 命令中显式指定派生数据路径：

xcodebuild \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -sdk iphoneos \
  -configuration Release \
  -derivedDataPath ./DerivedData \
  clean build

并发构建参数调优

Mac mini M4 有 10 核 CPU（4 性能核 + 6 能效核），Xcode 默认并发数通常为核心数。对于大型项目可以适当调低以避免内存压力：

defaults write com.apple.dt.Xcode IDEBuildOperationMaxNumberOfConcurrentCompileTasks 6

实测一个 80 个 Swift 文件的 SwiftUI 项目，在 16 GB RAM 的 M4 节点上 Clean Build 耗时约 4 分 12 秒，无任何 swap 压力。

代码签名与钥匙串：Archive 打包全流程

代码签名是 iOS CI/CD 流程中最容易出错的环节。在无图形界面的 CI 环境里，默认的 macOS Keychain 行为会与正常开发环境不同，需要显式管理钥匙串。

两种主流签名方案对比

手动 p12 方案：创建临时钥匙串

在 CI 环境里最稳妥的做法是每次 job 创建一个临时钥匙串，构建完成后删除，避免残留凭据：

# Create a temporary keychain
security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
security default-keychain -s build.keychain
security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
security set-keychain-settings -t 3600 -u build.keychain

# Import signing certificate
security import "$CERTIFICATE_P12_PATH" \
  -k build.keychain \
  -P "$P12_PASSWORD" \
  -T /usr/bin/codesign \
  -T /usr/bin/xcodebuild

# Allow xcodebuild to access the key without UI prompt
security set-key-partition-list \
  -S apple-tool:,apple: \
  -s -k "$KEYCHAIN_PASSWORD" build.keychain

其中 KEYCHAIN_PASSWORD、P12_PASSWORD 等敏感变量应存储在 GitHub Repository Secrets 中，通过 ${{ secrets.KEYCHAIN_PASSWORD }} 引用，绝对不能硬编码在 YAML 文件里。

执行 Archive 并导出 IPA

完整的 Archive → Export 流程分两步：先用 xcodebuild archive 生成 .xcarchive，再用 -exportArchive 导出 IPA。

# Step 1: Archive
xcodebuild archive \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -sdk iphoneos \
  -archivePath ./build/MyApp.xcarchive \
  CODE_SIGN_IDENTITY="Apple Distribution: Your Name (XXXXXXXX)" \
  DEVELOPMENT_TEAM="XXXXXXXX"

# Step 2: Export IPA
xcodebuild -exportArchive \
  -archivePath ./build/MyApp.xcarchive \
  -exportOptionsPlist ExportOptions.plist \
  -exportPath ./build/

ExportOptions.plist 是 Export 步骤的关键配置文件，需要包含 method（app-store / ad-hoc）、teamID 和 signingStyle 字段。可以先在 Xcode GUI 里手动 Export 一次，从生成的临时目录里找到该文件作为模板。

接入 fastlane 自动上传 TestFlight

IPA 打包出来后，最后一步是把它推送到 App Store Connect 的 TestFlight 通道。fastlane 的 pilot（也叫 upload_to_testflight）是目前最稳定的方案，支持 App Store Connect API Key 认证，无需 Apple ID 密码。

安装 fastlane

推荐使用 Bundler 管理 fastlane 版本，避免全局版本冲突：

# In project root, create Gemfile
source "https://rubygems.org"
gem "fastlane"

然后运行 bundle install，之后所有 fastlane 命令通过 bundle exec fastlane ... 调用。

配置 App Store Connect API Key

在 App Store Connect → Users and Access → Integrations → App Store Connect API 里创建 API Key，下载 .p8 文件，记下 Key ID 和 Issuer ID。

在 GitHub Secrets 中设置以下变量：

• ASC_API_KEY_ID：API Key 的 ID
• ASC_API_ISSUER_ID：Issuer ID
• ASC_API_KEY_CONTENT：.p8 文件的 Base64 编码内容

Fastfile 配置示例

lane :beta do
  api_key = app_store_connect_api_key(
    key_id: ENV["ASC_API_KEY_ID"],
    issuer_id: ENV["ASC_API_ISSUER_ID"],
    key_content: Base64.decode64(ENV["ASC_API_KEY_CONTENT"])
  )

  upload_to_testflight(
    api_key: api_key,
    ipa: "./build/MyApp.ipa",
    skip_waiting_for_build_processing: true
  )
end

在 GitHub Actions YAML 中调用：

- name: Upload to TestFlight
  env:
    ASC_API_KEY_ID: ${{ secrets.ASC_API_KEY_ID }}
    ASC_API_ISSUER_ID: ${{ secrets.ASC_API_ISSUER_ID }}
    ASC_API_KEY_CONTENT: ${{ secrets.ASC_API_KEY_CONTENT }}
  run: bundle exec fastlane beta

钥匙串常见报错集中排查

代码签名的报错信息往往语焉不详，以下是在 CI 无界面环境中最频繁出现的几类错误及其根因与解法。

调试技巧：在构建日志里看完整签名命令

在 xcodebuild 后加 | xcpretty -r json-compilation-database，或者直接去掉 xcpretty 管道查看原始日志，搜索 CodeSign 关键字可以看到实际执行的签名命令及参数，比 Xcode GUI 的错误面板信息量大得多。

另一个常见的调试命令是：

codesign -dv --verbose=4 ./build/MyApp.xcarchive/Products/Applications/MyApp.app

直接查看 .app 内嵌的签名信息，确认证书链是否完整。

Jenkins Agent 对照：迁移与取舍分析

如果你的团队已经有 Jenkins 基础设施，或者因为公司安全策略不能把代码推到 GitHub，Jenkins on Mac 是常见的替代方案。两者的核心差异体现在几个维度上。

从迁移角度来看，如果原先是 Jenkins 流水线，把 sh 'xcodebuild ...' 步骤迁移到 GitHub Actions YAML 的 run: 字段几乎是一比一对应的。最大的差异在于触发条件语法与并发控制：Jenkins 的 when { branch ... } 对应 GitHub Actions 的 on: push: branches:；Jenkins 的 lockable-resources 插件功能对应 GitHub Actions 的 concurrency: 组语法。

两套方案的共同前提是：都需要一台常驻在线、固定 macOS 版本的物理 Mac 作为 Agent/Runner 主机。这台机器是整条流水线稳定性的基础——它发热过载或版本漂移，CI 就会不可预期地失败。

很多中小团队在这里遇到的实际困境不是方案选择，而是：没有一台能长期跑 CI 的物理 Mac。本地办公用的 MacBook 内存往往只有 8 GB，大项目编译时散热降频明显，在持续 CI 负载下体验很差；而新采购一台 Mac mini 的成本加上场地、电力与维护开支，前期投入也不低。

云端独享 Mac：没有专属物理机时的固定构建方案

针对上面这个困境，按需租用独享云端 Mac 是一个值得认真评估的选项——既不需要前期硬件投入，又能获得一台专属的、固定环境的 macOS 构建节点。

以本文使用的 VPSRox Mac mini M4 节点为例：16 GB 统一内存 + 256 GB NVMe SSD 的标准配置，1 Gbps 独享带宽，单节点按天起租 $21.8，付款后 1–5 分钟自动交付，无合同锁定。

从 CI/CD 的角度，它相当于你租了一台永远在线、独享算力的 Mac mini，具体能做的事情与本地物理机没有差别：

• 安装任意版本 Xcode（通过 xcodes 工具管理），完全锁定构建环境
• 注册为 GitHub Actions 自托管 Runner 或 Jenkins Agent，本文所有步骤均可直接套用
• 利用 M4 的 10 核 CPU 和 38 TOPS Neural Engine，对含 Core ML 模型编译的项目有更好的表现
• 通过 Thunderbolt 5 并联扩展，将多台 Mac mini 组成私有构建集群（适合大型团队）

与 GitHub 托管 Runner 相比：按天租用的成本在高频构建场景下（如每天触发超过 30 次构建）往往低于 macOS Runner 超额计费；与自购 Mac mini 相比：无需前期采购预算、可按项目阶段调整租期（冲刺期加机、上线后减机）。

全球五个节点（新加坡、日本东京、韩国首尔、中国香港、美国东部）可以选择距离团队最近的位置，降低 git fetch 和依赖下载的延迟，进一步缩短整体构建时长。