Windows 上 iOS 开发接 CI,KXBuild 自托管 runner 出签名 ipa

给 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 证书目录。
相关推荐
十有八七1 小时前
手搓 Agent(一):先有大脑——大模型只会做一件事
前端·人工智能·后端
锋行天下1 小时前
「踩坑实录」给 LangGraph Agent 接两个 FastMCP,我被 langchain 偷偷改了工具名
前端·人工智能·后端
Resean02231 小时前
Spring 源码分析(一)IOC 容器总览与 refresh() 全景
java·后端·spring
苍何1 小时前
一句话出成片,我搭了个AI视频工厂
后端
bysking2 小时前
GitHub Actions 快速入门+场景实践案例
前端·后端·github
对象存储与RustFS4 小时前
对象锁遇上版本化:删掉的对象还在,真删的又删不掉
后端·docker·云原生
CappuccinoRose5 小时前
Redis 学习文档
redis·后端·学习·缓存·session·非关系型数据库·gossip
我不会起名字3226 小时前
WebSocket 停机与在线状态:Shutdown 返回后还需要清理什么
redis·后端·websocket·go·即时通讯·im·故障排查
疯华整猫7 小时前
别再抄 Flutter 了:2026 年 Android / iOS / 小程序跨端架构选型的四本成本账
android·前端·ios