给 iOS 项目接持续集成,默认答案一直是"租一台 macOS runner",而 GitHub 托管的 macOS runner 私有仓库按分钟计费,一条流水线跑下来不便宜。但"出一个能上架的 ipa"这步未必非 macOS 不可:在 Windows 或 Linux 上做 iOS 开发时,用 KXBuild 把自己的机器注册成自托管 runner,一条 kxbuild build -c Release 就能得到签好名、结构和 Xcode 导出一致的 ipa,GitHub 不按分钟收。下面先给核心命令和最小 workflow,再逐块讲自托管 runner、证书、构建号和自动上传几个关键点。VSCode插件
先看核心,一条命令出 ipa
CI 里真正干活的就这一行(以 GitHub Actions 为例,构建号用运行序号):
bash
kxbuild build ./MyApp.xcworkspace -s MyApp -c Release --clean \
--derivedDataDir ./out --skip-package-updates --ipa ./out/MyApp.ipa \
-D CODE_SIGN_KEYCHAIN="$KC" \
-D CODE_SIGN_IDENTITY="Apple Distribution" \
-D CURRENT_PROJECT_VERSION="$GITHUB_RUN_NUMBER"
几个参数的意思:-s -c 指定 scheme 和 Release 配置;--clean --derivedDataDir ./out 每次从干净目录构建、产物固定在 out;--skip-package-updates 让 Swift Package 严格按 Package.resolved 的版本、不访问远程;--ipa 指定 ipa 位置,旁边会同时生成上传要用的 MyApp.AppStoreInfo.plist;CURRENT_PROJECT_VERSION 用 CI 的运行号做构建号。命令成功退出码为 0、失败非 0,CI 据此判定步骤成败。只有 .xcodeproj 的工程,把第一个参数换成它即可。
最小的 workflow 骨架长这样:
yaml
jobs:
build-ios:
runs-on: [self-hosted, linux]
env:
KXBUILD_NO_UPDATE_CHECK: "1"
steps:
- uses: actions/checkout@v4
- name: Add KXBuild to PATH
run: |
echo "$HOME/kxbuild/bin" >> "$GITHUB_PATH"
- name: Build ipa
run: kxbuild build ./MyApp.xcworkspace -s MyApp -c Release --ipa ./out/MyApp.ipa ...
下面把每一块需要注意的地方拆开讲。
为什么必须是自托管 runner
这是最容易踩的前提:KXBuild 要在构建机上登录一次账号,而 GitHub 托管的 runner 每次运行都是一台全新机器、什么状态都不保留,登录没法持久化。自托管 runner 登录一次就一直可用,每次运行也不用重装工具链,GitHub 对自托管 runner 的 Actions 用量还不收分钟费。
准备构建机时有两个细节别漏:一是注册 runner 服务要用和安装 KXBuild 同一个用户 ,否则 workflow 里会 kxbuild: command not found;二是给这个用户设 KXBUILD_NO_UPDATE_CHECK=1 关掉自动更新检查,升级放到维护窗口手动 kxbuild update,不然两次构建用了不同版本的工具链,排查问题会很头疼。
证书怎么安全地进 CI
签名要三样:Apple Distribution 的 .p12、它的密码、App Store 类型描述文件。GitHub Secrets 只能存文本,所以 .p12 和 .mobileprovision 这类二进制先转成不换行的 base64 再存:
powershell
# Windows PowerShell,生成不换行的一整行
[Convert]::ToBase64String([IO.File]::ReadAllBytes("$PWD\distribution.p12")) | Set-Content -NoNewline p12.b64.txt
别用
certutil -encode,它会加 BEGIN/END 两行标记,解码时报错;Linux 上用base64 -w0,-w0才是不换行。
构建前在 workflow 里把它们解码写进一个临时目录,再写一个 password.properties(每行"文件名=密码",文件名要和 .p12 完全一致),构建时用 -D CODE_SIGN_KEYCHAIN 指向这个目录。关键收尾:自托管 runner 的磁盘会一直保留,最后一步一定要 if: always() 把证书目录 rm -rf 掉 ,否则私钥留在机器上。专门给一个团队用的构建机,也可以把证书一次性放进 ~/kxbuild/keychain 全工程共用,代价是能在这台 runner 跑任务的人都能拿到私钥。
构建号,避免 Re-run 撞车重复
App Store Connect 要求同一版本号下每次上传的构建号都比上一次大,重复或变小直接被拒。最简单的做法是用运行序号:-D CURRENT_PROJECT_VERSION="$GITHUB_RUN_NUMBER"。但有个坑:GitHub 上点 Re-run 时 GITHUB_RUN_NUMBER 不变,上一次已经传成功的话,重跑就因构建号重复失败。把尝试次数拼成第二段能避开:
bash
BUILD_NUMBER="${GITHUB_RUN_NUMBER}.${GITHUB_RUN_ATTEMPT}"
多台机器、多条流水线都往同一个 App 传的,运行序号可能撞,用 UTC 时间更稳:date -u +%Y%m%d.%H%M(构建号格式是一到三段用点分隔的整数,这是 Apple 规定)。还有个前提常被忘:-D 能覆盖构建号,前提是 Info.plist 里写的是 $(CURRENT_PROJECT_VERSION) 变量而不是写死的数字,老工程要先改过来,有 App 扩展的扩展 Info.plist 也要一起改。
自动上传,不用 Mac 也能传 App Store
出了 ipa 还想在流水线里直接上传的,用 Apple 的命令行版 Transporter(iTMSTransporter)加 App Store Connect 的团队 API 密钥 ,它有 Windows 和 Linux 版,-apiKey/-apiIssuer 认证,不用 Apple 账号密码和验证码:
bash
iTMSTransporter -m upload -assetFile out/MyApp.ipa \
-assetDescription out/MyApp.AppStoreInfo.plist \
-apiKey "$ASC_KEY_ID" -apiIssuer "$ASC_ISSUER_ID"
那个 -assetDescription 要的 AppStoreInfo.plist,正是前面 kxbuild build 时在 ipa 旁边生成的,两者要来自同一次构建。.p8 私钥只能下载一次、Apple 不留副本,丢了只能撤销重建,所以要当私钥一样存进 Secret。只想手动传的,用 Appuploader 更简单,不必上 Transporter。
它干不了什么
不吹全能。自托管 Linux runner 上有两件事做不到:Metal 着色器 (工程里有 .metal 文件)在 Linux 上没编译器,得换 Windows 自托管 runner;iOS 模拟器测试、UI 测试也跑不了。所以要跑模拟器测试的项目,合理的拆法是两个 job:测试 job 用托管 macOS runner,打包 job 用自托管 Linux runner 出 ipa,既省了打包的分钟费,又保留了测试能力。
和托管 macOS runner 摆一起看:
| 对比项 | 自托管 Linux + KXBuild | 托管 macOS + Xcode |
|---|---|---|
| 计费 | GitHub 不按分钟收,机器电费自理 | 私有仓库按分钟计费 |
| 工具链 | 装一次,之后直接构建 | 镜像预装 Xcode |
| 出 ipa | kxbuild build -c Release 一步 |
archive 再 exportArchive |
| Metal / 模拟器测试 | 不支持 | 支持 |
GitHub 的计费标准以其当前公布为准(截至 2026 年 10 月,自托管 runner 的 Actions 用量免费)。只出 ipa、不跑模拟器测试的项目,用自托管 Linux runner 最省。
两个安全隐患
- 只在私有仓库用自托管 runner。公开仓库谁都能提 PR、在你的构建机上跑代码,GitHub 官方也明确不建议。
- 证书和密钥不要进日志 。Actions 会把 Secret 值替换成
***,但解码后的文件内容不会被遮,脚本里别cat证书目录。