Capacitor と Capgo Build を使って Linux から iOS アプリをビルドする

Linux は Capacitor アプリの開発に最適な環境であり、Android のビルドも妥協なく行えます。しかし iOS は例外です。Xcode や Apple の署名ツールは macOS でしか動作しません。解決策は、デスクの下に Mac mini を置くことではありません。iOS プロジェクトをローカルで生成し、クラウド上の macOS でコンパイルすることです。

このガイドは、以下の Linux 版です： Capacitor と Capgo Build を使って Windows から iOS アプリをビルドする。Linux 特有の要素である OpenSSL 証明書、Linux シェル、および Linux ランナーからの CI について解説します。

役割分担

Capacitor アプリには2つのビルドがあります：

• Webビルド1. フレームワークの出力（ dist/）。これはLinux上で完了します。
• Native Build2. 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なしで署名用リソースを作成する

以下の3つが必要です：Apple Distribution証明書、 .p12App Store用プロビジョニングプロファイル、および App Store Connect の API キーです。いずれも Keychain Access は不要です。

OpenSSLを使用したDistribution証明書

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 Certificates, Identifiers & Profiles で 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 パスワードが正しくても invalid password エラーになることがあります。OpenSSL を直接触りたくない場合は、 iOS証明書ジェネレーター はブラウザでも同じことができます。

プロビジョニングプロファイルと API キー

Apple Developerポータルで、新しい証明書を使うBundle ID用のApp Storeプロファイルを作成し、次をダウンロードします .mobileprovision。App Store Connectで、App Managerロールの API キーを作成し、次をダウンロードします .p8。Key IDとIssuer IDをメモしておいてください。 iOSビルドガイド では各画面を表示します。

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に拒否されます。

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 installXcodeでアーカイブ、証明書での署名を行い、ログをターミナルにストリーミングします。API キーが設定されていれば、ビルド完了後に自動でTestFlightへ送信されます。iPhoneにTestFlightアプリをインストールして実行してください。

ビルドに失敗した場合は、以下を追加することで自動診断が可能です。 --ai-analytics; AIビルド診断機能が Xcodeのログを読み取り、修正方法を解説します。

6) TestFlightを使わないテスター向けのAd hocビルド

UDIDで登録されたQAデバイス向けには、Ad Hocプロファイルを使用し、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ランナーでの自動化

同じコマンドがどの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 に格納されるため、ランナーにはトークンのみが必要です。または、CIの .env を使用して bunx @capgo/cli@latest build credentials manage をエクスポートして、値をシークレットとして渡すこともできます。詳細は 認証情報の管理.

8) Native Buildなしでの日常的なイテレーション

TestFlightのビルドが一度作成されれば、ほとんどの変更はWeb側の変更です。これらは Capgo Live Updates でプッシュできます:

bun run build
bunx @capgo/cli@latest bundle upload --channel production

予約 build request プラグインの追加、権限の変更、アイコンの変更、および Capacitor のアップグレード用。

Linux特有の落とし穴

• 忘れました cap sync ios: IPAに古いUIが表示されます。リクエスト前に必ずSyncしてください。
• ios/ における .gitignore: CLI をディスクからアップロードしているためビルドは通りますが、チームメンバーやCIにはネイティブプロジェクトが反映されません。必ずコミットしてください。
• .p12 パスワードが拒否されました: 次の方法で再生成してください -legacy.
• Apple認証に失敗しました: 時刻のズレです。NTPを有効にしてください。
• プラグインを追加しましたが、ネイティブの再ビルドを忘れています: Capacitor プラグインを追加するとネイティブバイナリが変更されます。そのプラグインを呼び出すWeb側の変更をリリースする前に、新しいクラウドビルドを実行し、ストアへの申請を行ってください。

まとめ

LinuxではXcodeを実行できませんが、その必要もありません。生成するには ios/ with Capacitor, build certificates with OpenSSL, and let Capgo Build compile, sign and send to TestFlight. With Live Updates for the web layer, a Linux-only team ships iOS as routinely as Android. For the full environment setup, read Linuxでの Capacitor 開発.