iOS-App unter Linux bauen mit Capacitor und Capgo Build

Linux ist eine ideale Umgebung für die Entwicklung von Capacitor Apps, und auch Android lässt sich ohne Kompromisse damit deployen. iOS ist die Ausnahme: Xcode und Apples Signing-Tools laufen nur auf macOS. Die Lösung ist nicht ein Mac mini unter dem Schreibtisch, sondern das lokale Generieren des iOS-Projekts und das Kompilieren auf macOS in der Cloud.

Dieser Guide ist die Linux-Version von iOS-App von Windows aus bauen mit Capacitor und Capgo Build. Er behandelt die Unterschiede unter Linux: OpenSSL-Zertifikate, die Linux-Shell und CI über Linux-Runner.

Die Arbeitsteilung

Eine Capacitor App hat zwei Builds:

• Web-Build: dein Framework-Output in dist/. Erledigt auf Linux.
• Native Build: Xcode-Archive, Signing, Upload. Erledigt durch Capgo Build auf Apple Silicon Maschinen mit aktuellem macOS und Xcode.

Der CLI lädt das vorbereitete ios/ Projekt von deiner Maschine hoch. Nichts muss in einem Git-Host liegen und keine privaten Registry-Credentials verlassen deinen Rechner, da Dependency-Installs und cap sync lokal vor dem Upload stattfinden.

Voraussetzungen

• Eine Capacitor App, die lokal gebaut wird (jedes Framework).
• Node 20+ oder Bun unter Linux.
• Eine Mitgliedschaft im Apple Developer Program.
• OpenSSL (unter fast jeder Distribution vorinstalliert).
• Ein Capgo Account und die registrierte App bei bunx @capgo/cli@latest app add.

1) Das iOS-Projekt unter Linux generieren

bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add ios

Du siehst dann etwas wie Skipping pod install because CocoaPods is not installed. So gewollt. Der ios/ Ordner existiert und sollte committet werden; er enthält deine Bundle ID, die Info.plist, Icons und native Einstellungen.

2) Web-Assets vor jedem Build synchronisieren

bun run build
bunx cap sync ios

cap sync kopiert dist/ in ios/App/App/public und aktualisiert Plugin-Referenzen. Capgo kompiliert den Inhalt von ios/, sodass ein nicht synchronisiertes Projekt die alte UI ausliefert.

3) Signing-Material ohne Mac erstellen

Du brauchst drei Dinge: ein Apple-Distribution-Zertifikat als .p12ein App Store Provisioning Profile und einen App Store Connect API Key. Nichts davon erfordert Keychain Access.

Distribution-Zertifikat mit 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"

Upload ios_distribution.csr unter Certificates, Identifiers & Profiles wähle Apple Distribution und lade distribution.cerherunter. Konvertieren und bündeln:

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

Der -legacy Flag ist bei OpenSSL 3 wichtig. Ohne dieses lehnen Apples Tools den .p12 mit einem Fehler wegen ungültigem Passwort, obwohl das Passwort richtig ist. Wenn du OpenSSL lieber nicht anfassen möchtest, dann iOS-Zertifikatsgenerator macht dasselbe im Browser.

Provisioning-Profil und API Key

Erstelle im Apple Developer Portal ein App Store Profil für deine Bundle ID, das das neue Zertifikat nutzt, und lade die .mobileprovision. Erstelle in App Store Connect einen API Key mit der Rolle „App Manager“ und lade den .p8; notiere dir die Key ID und die Issuer ID. Die iOS-Build-Anleitung zeigt jeden Screen.

Willst du ein Profil unter Linux inspizieren? openssl smime -inform der -verify -noverify -in profile.mobileprovision gibt die eingebettete plist aus.

4) Speichere die Credentials in 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

Oder führe bunx @capgo/cli@latest build init --platform ios für die geführte Version aus. Unter Linux ist der App Store Connect Key-Schritt manuell; alles andere wird per Prompt abgefragt.

Falls Apple den Key wegen eines Authentifizierungsfehlers ablehnt, synchronisiere deine Uhrzeit. Das JWT wird mit der lokalen Zeit signiert, und Apple lehnt Tokens mit zu großer Zeitabweichung ab:

timedatectl status
sudo timedatectl set-ntp true

5) Build anfordern

bun run build
bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

Das vorbereitete ios/ Projekt wird hochgeladen, Capgo führt den pod installProzess aus, archiviert mit Xcode, signiert mit deinem Zertifikat und streamt die Logs in dein Terminal. Ist der API Key konfiguriert, wird der Build nach Abschluss an TestFlight übermittelt. Installiere die TestFlight-App auf einem iPhone, um ihn zu testen.

Fehlgeschlagene Builds können automatisch diagnostiziert werden, indem du --ai-analytics; die KI-Build-Diagnose liest das Xcode-Log und erklärt die Lösung.

6) Ad-hoc-Builds für Tester ohne TestFlight

Für ein per UDID registriertes QA-Gerät verwenden Sie ein Ad Hoc-Profil und bewahren die IPA als Artifact auf:

bunx @capgo/cli@latest build request com.example.app \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

Das CLI gibt einen zeitlich begrenzten Download-Link aus. Füge --output-record build.json um den Link und einen QR-Code code für einen Tester zu speichern.

7) Automatisierung über einen Linux CI-Runner

Die gleichen Befehle laufen in jeder Linux CI. Hier ein GitHub Actions Beispiel:

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 }}

In Schritt 4 gespeicherte Credentials liegen in Capgo, sodass der Runner nur den Token benötigt. Alternativ kannst du CI- .env mit bunx @capgo/cli@latest build credentials manage und übergebe die Werte als Secrets; siehe Verwaltung von Credentials.

8) Tägliche Iterationen ohne Native Builds

Sobald der TestFlight-Build steht, sind die meisten Änderungen Web-Änderungen. Pushe sie mit Capgo Live Updates:

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

Reservieren build request für Plugin-Erweiterungen, Berechtigungsänderungen, Icon-Anpassungen und Capacitor Upgrades.

Linux-Fallstricke

• Vergessen cap sync ios: Die IPA zeigt das alte UI. Vor jeder Anfrage synchronisieren.
• ios/ in .gitignore: Die CLI werden von der Festplatte hochgeladen, sodass der Build zwar läuft, deine Teammitglieder und die CI aber das native Projekt nicht haben. Commit es.
• .p12 Passwort abgelehnt: Neu generieren mit -legacy.
• Apple-Authentifizierung fehlgeschlagen: Clock Drift. NTP aktivieren.
• Plugin hinzugefügt, aber den Native Build vergessen: Das Hinzufügen eines Capacitor Plugins ändert die native Binary. Führe einen neuen Cloud Build und eine Store-Submission durch, bevor du Web-Änderungen veröffentlichst, die dieses Plugin nutzen.

Zusammenfassung

Linux kann Xcode nicht ausführen, muss es aber auch nicht. Erstelle ios/ mit Capacitor, erstelle Build-Zertifikate mit OpenSSL und lass Capgo Build kompilieren, signieren und an TestFlight senden. Dank Live Updates für den Web-Layer liefert ein reines Linux-Team iOS genauso selbstverständlich aus wie Android. Für das komplette Environment-Setup lies Capacitor-Entwicklung unter Linux.