Wie man sich bei Capacitor anmeldet und eine App im Cloud bereitstellt

Um ein Capacitor-App im Cloud zu signieren und zu bauen, erstellen Sie Ihr Signiermaterial einmal (einen Android-Keystore, ein iOS-Distributionszertifikat und ein Provisioningprofil), geben Sie es an einen Cloud-Build-Dienst weiter und führen Sie dann Builds von Ihrem Terminal oder CI aus. Der Dienst kompiliert das native Projekt, signiert es und kann es direkt auf TestFlight oder Google Play hochladen. Diese Anleitung behandelt jeden Signierungsdatei, wie man sie ohne Mac erstellt, wie man sie mit Capgo Build einrichtet und wie man signierte Builds sicher automatisiert.

Was bedeutet “Signieren im Cloud”

Beide Stores akzeptieren nur signierte Binärdateien. Das Signieren beweist, dass der Build von Ihnen stammt und dass niemand ihn danach geändert hat. Lokal verbergen Xcode und Android Studio die meisten dieser Informationen. Im Cloud ist nichts implizit, daher müssen Sie genau wissen, welche Dateien beteiligt sind:

Halten Sie diese aus Git heraus. Alles darunter speichert sie in Ihrer lokalen Anmeldeinformationen-Datei oder im geheimen Speicher Ihres CI.

Erstellen Sie das Upload-Keystore

Erstellen Sie das Upload-Zertifikat

If die App bereits auf Google Play ist, wiederverwenden Sie den bestehenden Keystore. Die Signierung einer Aktualisierung mit einem anderen Schlüssel wird abgelehnt, es sei denn, Sie gehen durch die Upload-Schlüssel-Restetzung im Play Console.

Für eine neue App:

keytool -genkeypair -v \
  -storetype PKCS12 \
  -keystore release.jks \
  -alias upload \
  -keyalg RSA -keysize 2048 \
  -validity 10000

Hinweise:

• Google Play erfordert, dass der Schlüssel bis mindestens den 22. Oktober 2033 gültig ist. -validity 10000 (ca. 27 Jahre) deckt das ab.
• Mit dem PKCS12-Speicher-Typ ist das Schlüsselpasswort gleich dem Speicher-Passwort.
• Kein JDK zur Hand? Der Android-Keystore-Generator erzeugt denselben Datei im Browser.

Play App Signing und die Upload-Schlüssel-Restetzung

Neue Apps auf Google Play verwenden Play App Signing. Google hält den Anwendungs-Schlüssel und wiederrichtet, was die Benutzer herunterladen. Upload-Schlüssel. Wenn Sie ihn verlieren, kann das Support-Team von Play Console einen neuen Upload-Schlüssel registrieren, weshalb der Verlust ihn nicht zum Desaster macht. Machen Sie ihn trotzdem sicher.

Dienstkonten für Uploads

Um aus der Cloud hochzuladen, erstellen Sie ein Dienstkonto in Google Cloud, aktivieren Sie die Google Play Android-Entwickler-Einrichtung API, laden Sie die JSON-Schlüsseldatei herunter und laden Sie das Dienstkonto in Play Console unter Benutzer und Berechtigungen mit Freigabeberechtigungen für Ihre App. Capgo’s Onboarding kann dies über Google-Anmeldung durchführen, wie unten gezeigt.

iOS-Zertifizierung

Die drei Apple-Stücke

• Apple-Distribution-Zertifikat. Eines pro Team reicht aus, gültig für ein Jahr. Apple beschränkt die Anzahl, die Sie haben können, also erstellen Sie nicht eines pro Entwickler.
• Zertifizierungsprofil. Verknüpft die Bundle-ID, das Zertifikat und Fähigkeiten wie Push-Benachrichtigungen. Verwenden Sie ein App Store Connect Profil für TestFlight und den App Store, und ein Ad hoc Profil für Installationen auf registrierten Geräten. Jedes App-Extension (Widget, Teilen-Extension, Benachrichtigungsdienst) benötigt sein eigenes Profil.
• App Store Connect API-Schlüssel. Erstellt unter Benutzer und Zugriff > Integrations mit Zugriff auf App Manager. Der .p8 Datei-Download erfolgt nur einmal.

Sie benötigen Administrator- oder Kontoinhaber-Rechte auf der Apple-Entwickler-Team, um diese zu erstellen.

Erstellen Sie ein Zertifikat ohne Mac

The Keychain Access-Flow benötigt macOS, aber OpenSSL funktioniert überall:

# 1. Private key and certificate signing request
openssl req -new -newkey rsa:2048 -nodes \
  -keyout dist.key -out dist.csr \
  -subj "/emailAddress=dev@example.com/CN=Example Inc/C=US"

# 2. Upload dist.csr at developer.apple.com > Certificates > + > Apple Distribution
#    and download distribution.cer

# 3. Convert and bundle into a .p12
openssl x509 -inform DER -in distribution.cer -out distribution.pem
openssl pkcs12 -export -legacy \
  -inkey dist.key -in distribution.pem \
  -out distribution.p12 -passout pass:choose-a-password

The -legacy Die Flagge spielt bei OpenSSL 3 eine Rolle: Ohne sie können macOS-Build-Maschinen versagen, die Zertifikate zu importieren. .p12 mit „MAC-Verifizierung fehlgeschlagen“. Der browserbasierte iOS-Zertifikatsgenerator verwende die gleichen Schritte, wenn du lieber nicht in einem Terminal arbeitest.

Dann erstellen Sie das Provisioning-Profil im Entwicklerportal (Profiles > + > App Store Connect), wählen Sie Ihr App-ID und das neue Zertifikat aus und laden Sie es herunter.

Konfigurieren Sie das Signieren mit Capgo Build

Capgo Build compiles and signs Capacitor apps on Capgo-managed machines, so you can build iOS from Windows or Linux. Start by logging in and registering the app:

bunx @capgo/cli@latest login
bunx @capgo/cli@latest app add

Option A: geführte Einrichtung (empfohlen)

bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build init --platform android

Bei iOS erstellt die Einrichtung entweder eine neue oder verwendet eine bestehende Zertifikats- und App-Store-Profil-Vorlage mit Ihrem App-Store-Connect-Schlüssel API. Bei macOS kann sie Sie auch durch die Erstellung dieses Schlüssels API führen. Bei Android erstellt sie entweder eine neue oder importiert eine bestehende Keystore und kann die Google Cloud-Dienstkonten und die Einladung zum Google Play-Console über Google-Anmeldedaten bereitstellen. Am Ende bietet sie Ihnen an, das erste Build zu starten.

Option B: Speichern Sie bestehende Dateien

Wenn Sie bereits die Dateien aus den vorherigen Abschnitten haben:

# iOS
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./distribution.p12 \
  --p12-password "choose-a-password" \
  --ios-provisioning-profile ./AppStore.mobileprovision \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id ABC1234567 \
  --apple-issuer-id 00000000-0000-0000-0000-000000000000 \
  --apple-team-id TEAM123456

# Android
bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.jks \
  --keystore-alias upload \
  --keystore-key-password "store-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-service-account.json

Für Apps mit Erweiterungen wiederholen Sie --ios-provisioning-profile mit einem bundleId=path Mapping für jede Zielplattform:

  --ios-provisioning-profile com.example.app=./App.mobileprovision \
  --ios-provisioning-profile com.example.app.widget=./Widget.mobileprovision

Die Anmeldeinformationen werden in ~/.capgo-credentials/credentials.json, sortiert nach der App-ID und der Plattform. --local zu speichern .capgo-credentials.json anstatt in dem Projekt zu speichern, und fügen Sie diese Datei zu .gitignorehinzu. Überprüfen Sie, was gespeichert wird mit bunx @capgo/cli@latest build credentials list.

Auslösen eines signierten Builds

Vorbereiten Sie das native Projekt, dann die Anfrage zum Build:

bun run build
bunx cap sync

# iOS: sign with the App Store profile and upload to TestFlight
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

# Android: sign the AAB and upload to the internal track
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release --android-track internal

Die Protokolle fließen in Ihr Terminal ein. Eine Vorbereitungsscan überprüft die Ablaufdatum der Zertifikate, Passwörter und Profilzuordnungen, bevor etwas hochgeladen wird, sodass die meisten Signierfehler in Sekunden statt in Minuten ausgelöst werden. Führen Sie es auf eigene Faust mit bunx @capgo/cli@latest build prescan --platform ios.

Nützliche Variationen:

Für ad-hoc- Builds sammeln Sie zunächst die Geräte-UDIDs mit dem iOS UDID Finder und fügen Sie sie zur Profil

Automatisieren Sie die signierten Builds in CI

In CI werden die Anmeldeinformationen als Umgebungsvariablen übergeben und nicht als Anmeldeinformationen-Datei. Die CLI exportiert genau das, was Sie benötigen:

bunx @capgo/cli@latest build credentials manage --appId com.example.app
# choose "Export to .env"

GitHub, drücken Sie jede Zeile in einem Befehl in die Repository-Secrets ein und löschen Sie dann die Datei:

gh secret set -f .env.capgo.com.example.app
gh secret set CAPGO_TOKEN --body "your-capgo-api-key"
rm .env.capgo.com.example.app

Ein Release-Workflow, der sowohl Plattformen auf einem Tag signiert und versendet:

name: Signed release
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}
      - run: bunx @capgo/cli@latest build request com.example.app --platform ${{ matrix.platform }} --build-mode release
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

Die Aufgabe läuft auf Linux. Kein macOS-Runner, keine Keychain-Befehle, keine Fastlane. Die gleichen Umgebungsvariablen funktionieren in jedem CI: GitLab CI/CD-Umgebungsvariablen, Bitbucket gesicherte Variablen, Gitea-Secrets oder Azure DevOps-Gruppen von Variablen. Plattform-spezifische Anleitungen: Bitbucket Pipelines, Gitea Actions, und die GitHub-Dokumentation zu Aktionen.

Wie Ihre Schlüssel behandelt werden

Auf eine faire Frage, bevor Sie Schlüssel für jede Cloud-Dienst übergeben. Mit Capgo Build:

• Die Zugangsdaten befinden sich auf Ihrem Computer (~/.capgo-credentials/) oder in Ihrem CI-Secret-Speicher. Capgo hält keine Kryptobox Ihrer Schlüssel.
• Für jeden Build sendet CLI sie über HTTPS. Sie werden nur während dieses Builds verwendet und gelöscht, wenn er abgeschlossen ist.
• Nur das vorbereitete native Projekt wird hochgeladen. Ihre Web-Quelle, .gitund .env Dateien werden nicht.
• Die gebauten Apps gehen direkt in App Store Connect oder Google Play oder auf eine zeitbegrenzte Download-Link, wenn Sie einen anfordern.

Der Handel: Die Aktualisierung einer Zugangsdaten bedeutet, dass Sie Ihre CI-Secrets selbst aktualisieren müssen. Re-export mit build credentials manage und drücken Sie die Datei erneut.

Abgelaufen und Rotation

Setzen Sie die Apple-Daten in einem geteilten Kalender. Ein abgelaufenes Zertifikat beeinflusst Apps, die bereits auf den Geräten der Benutzer installiert sind, aber blockiert jede neue Build.

Fehlertreiber

Mehrere Fehler sind im Capgo-Build-Fehlersuchguide und CI/CD für Capacitor: häufige Fehlerquellen.

After dem ersten signierten Build

Signed native Builds sind nur erforderlich, wenn native code-Änderungen vorgenommen werden. Für JavaScript-, CSS- und HTML-Änderungen können Sie ein live update zu installierten Apps wechseln und Build-Store-Angebote für Releases speichern, die Plugins oder native Konfigurationen betreffen. Wenn Sie von einem Mac-basierten Setup kommen, Bauen Sie eine iOS App von Windows mit Capgo Bauen zeigt die gesamte Workflow ohne macOS.