把一台 Mac mini
变成你的 iOS 构建机

准备一台专用的 Mac

构建机最好专用：环境不被日常使用打乱，也不会因为合盖或休眠中断任务。远程租用的 Mac mini 7×24 在线，正好合适。登录后先为 runner 建一个单独的 macOS 用户（例如 runner），避免流水线拿到你个人账户的钥匙串和文件。

确认机器不会自动休眠：系统设置 → 能耗 → 打开「显示器关闭时防止自动进入睡眠」；也可以用管理员账户执行：

sudo pmset -a sleep 0 disksleep 0

安装 Xcode 与命令行工具

从 App Store 或 Apple Developer 下载 Xcode，安装后执行首次启动和许可确认，并安装需要的模拟器运行时：

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
xcodebuild -runFirstLaunch
xcodebuild -downloadPlatform iOS

需要多个 Xcode 版本时，可以用 xcodes 管理，并在流水线里用 DEVELOPER_DIR 指定版本。Flutter 项目再装 Flutter SDK 与 CocoaPods（brew install cocoapods）。

注册 GitHub Actions 自托管 Runner

在仓库或组织的 Settings → Actions → Runners → New self-hosted runner，选择 macOS、ARM64，页面会给出带临时令牌的命令。以 runner 用户登录后按页面执行，大致如下（以页面上的版本号和令牌为准）：

mkdir actions-runner && cd actions-runner
curl -o actions-runner-osx-arm64.tar.gz -L <页面给出的下载地址>
tar xzf ./actions-runner-osx-arm64.tar.gz
./config.sh --url https://github.com/<组织>/<仓库> --token <页面给出的令牌> --labels ios,xcode

自定义标签（如 ios、xcode）方便在流水线里精确指定这台机器。

安装为服务，重启后自动运行

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

runner 会以 launchd 服务运行，机器重启后自动上线。在 GitHub 的 Runners 页面能看到它的状态变为 Idle。

写一条构建流水线

在 .github/workflows/ios.yml 里用 runs-on 指向自托管标签。因为环境常驻，依赖和 DerivedData 会被复用，增量构建明显更快：

name: iOS
on: [push]
jobs:
  build:
    runs-on: [self-hosted, macOS, ARM64, ios]
    steps:
      - uses: actions/checkout@v4
      - name: Build and test
        run: |
          xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' test

签名与上传 TestFlight

推荐用 fastlane：match 把证书和描述文件加密存进私有仓库，构建时下载到临时钥匙串；pilot 或 upload_to_testflight 用 App Store Connect API Key 上传，不需要在机器上登录 Apple ID。

API Key、match 密码等放在 GitHub Secrets 里，通过环境变量传给 fastlane，不要写进仓库或机器上的明文文件。退租前删除 runner（./svc.sh uninstall、./config.sh remove），并在 App Store Connect 撤销不再使用的密钥。

常见问题