Linux 是开发 Capacitor 应用的舒适环境,Android 应用也能从这里无缝发布。iOS 是个例外:Xcode 和 Apple 的签名工具只能在 macOS 上运行。解决方案不是把 Mac mini 塞在桌下,而是在本地生成 iOS 项目,然后在云端 macOS 上编译。
本指南是 在 Windows 上使用 Capacitor 和 Capgo Build 构建 iOS 应用的 Linux 版本。它涵盖了 Linux 上的不同之处:OpenSSL 证书、Linux shell 以及从 Linux runner 运行的 CI。
分工
一个 Capacitor 应用有两种构建:
- Web 构建:你的框架输出在
dist/。在 Linux 上完成。 - Native Build:Xcode 归档、签名、上传。由 Capgo 构建 在运行当前 macOS 和 Xcode 的 Apple Silicon 机器上完成。
CLI 会上传准备好的 ios/ 项目从你的机器。无需托管在 Git 上,私有注册表凭据也不会离开你的设备,因为依赖安装和 cap sync 在上传前在本地完成。
前提条件
- 支持本地构建(任何框架)的 Capacitor 应用。
- Linux 上的 Node 20+ 或 Bun。
- Apple Developer Program 会员资格。
- OpenSSL(几乎所有发行版都默认安装)。
- 一个 Capgo 账号,以及已注册到该账号的应用
bunx @capgo/cli@latest app add.
1) 在 Linux 上生成 iOS 项目
bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add ios
你会看到类似以下的内容 Skipping pod install because CocoaPods is not installed。这是正常的。该 ios/ 文件夹已存在,应当提交;它包含了你的 bundle ID、Info.plist、图标和原生配置。
2) 每次构建前同步 Web 资源
bun run build
bunx cap sync ios
cap sync 复制 dist/ 为 ios/App/App/public 并更新插件引用。Capgo 会编译当前内容 ios/,因此未同步的项目会发布你之前的 UI。
3) 无需 Mac 即可创建签名材料
你需要三样东西:一个 Apple Distribution 证书,作为 .p12,一个 App Store 描述文件,以及一个 App Store Connect API 密钥。这些都不需要 Keychain Access。
使用 OpenSSL 生成发布证书
openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
-subj "/emailAddress=you@example.com/CN=Your Name/C=US"
上传 ios_distribution.csr 在“证书、标识符和描述文件”中,选择 Apple Distribution,然后下载 distribution.cer。转换并打包:
openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
-out ios_distribution.p12 -legacy
本指南中介绍的 -legacy 在 OpenSSL 3 中,该 flag 至关重要。缺少它,Apple 的工具链会拒绝 .p12 ,即使密码正确,也会报出“无效密码”错误。如果你不想折腾 OpenSSL,可以 iOS 证书生成器 在浏览器中执行相同操作。
描述文件与 API 密钥
在 Apple Developer 门户中,为您的 bundle ID 创建一个使用新证书的 App Store 配置文件,并下载 .mobileprovision。在 App Store Connect 中,创建一个具有 App Manager 角色的 API 密钥并下载 .p8;记下 Key ID 和 Issuer ID。 iOS Build 指南 展示了每个屏幕。
想在 Linux 上检查配置文件? openssl smime -inform der -verify -noverify -in profile.mobileprovision 会打印出嵌入的 plist。
4) 将凭据保存到 Capgo
bunx @capgo/cli@latest login
bunx @capgo/cli@latest build credentials save \
--platform ios \
--apple-team-id "TEAMID" \
--apple-key ./AuthKey_KEYID.p8 \
--apple-key-id "KEYID" \
--apple-issuer-id "issuer-uuid" \
--certificate ./ios_distribution.p12 \
--ios-provisioning-profile ./App_Store.mobileprovision
或者运行 bunx @capgo/cli@latest build init --platform ios 来使用引导模式。在 Linux 上,App Store Connect 密钥步骤需要手动完成;其余步骤都会有提示。
如果 Apple 因身份验证错误拒绝该密钥,请同步系统时间。JWT 使用本地时间签名,Apple 会拒绝偏差过大的 token:
timedatectl status
sudo timedatectl set-ntp true
5) 发起构建
bun run build
bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
准备好的 ios/ 项目会上传,Capgo 会运行 pod install,用 Xcode 归档,用你的证书签名,并将日志流式输出到终端。配置好 API 密钥后,构建完成后会提交到 TestFlight。在 iPhone 上安装 TestFlight 应用即可运行。
失败的构建可以通过添加以下功能自动诊断: --ai-analytics; AI 构建诊断 读取 Xcode 日志并说明修复方法。
6) 为没有 TestFlight 的测试人员提供 Ad hoc 构建
对于通过 UDID 注册的 QA 设备,请使用 Ad Hoc profile,并将 IPA 作为产物保留:
bunx @capgo/cli@latest build request com.example.app \
--platform ios \
--ios-distribution ad_hoc \
--output-upload
CLI 会输出一个限时下载链接。添加 --output-record build.json 以保存链接,以及给测试人员的 QR code。
7) 在 Linux CI runner 上实现自动化
相同的命令可在任何 Linux CI 上运行。下面是一个 GitHub Actions 示例:
name: iOS build
on:
workflow_dispatch:
jobs:
ios:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun run build
- run: bunx cap sync ios
- run: bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
env:
CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
第 4 步保存的凭据存储在 Capgo 中,因此 runner 只需要 token。或者,导出 CI .env 配合 bunx @capgo/cli@latest build credentials manage 并将这些值作为 secrets 传入;参见 凭据管理.
8) 无需原生构建的日常迭代
TestFlight 构建就绪后,大部分改动都是 Web 改动。使用 Capgo Live Update:
bun run build
bunx @capgo/cli@latest bundle upload --channel production
仅在 build request 用于新增插件、权限变更、图标变更以及 Capacitor 升级。
Linux 环境下的坑
- 忘记
cap sync ios:IPA 显示的还是旧 UI。每次请求前先同步。 ios/中的.gitignore:CLI 是从磁盘上传的,所以仍能构建,但队友和 CI 不会有原生项目。请提交它。.p12密码被拒绝:请使用以下方式重新生成-legacy.- Apple 身份验证失败:时钟漂移。请启用 NTP。
- 添加了插件,却忘了重新构建原生项目:添加 Capacitor 插件会改变原生二进制文件。在发布调用该插件的 Web 更改之前,请运行新的云端构建并提交到应用商店。
总结
Linux 无法运行 Xcode,但这并不重要。生成 ios/ 使用 Capacitor,通过 OpenSSL 生成构建证书,并让 Capgo Build 完成编译、签名并发送至 TestFlight。借助 Web 层的 Live Update,纯 Linux 团队可以像发布 Android 一样轻松发布 iOS。有关完整的环境设置,请阅读 在 Linux 上开发 Capacitor.