Zusätzliche Ressourcen

Lösungen für häufige Probleme bei der Erstellung nativer Apps mit Capgo Cloud Build.

Build-Fehler

”Upload failed” or “Connection timeout”

Abschnitt mit dem Titel „ ,

• Upload fehlgeschlagen“ oder „Verbindungstimeout““
• Symptome:

Der Build scheitert während des Projektuploads

1. Timeout-Fehler nach 60 Sekunden

   # Test connection to Capgo
   curl -I https://api.capgo.app

2. Terminalfenster

   • Auf die Zwischenablage kopieren node_modules/ wird nicht hochgeladen (sollte automatisch ausgeschlossen werden)
   • Überprüfen Sie nach großen Dateien in Ihrem Projekt:

   find . -type f -size +10M

3. Überprüfen Sie die Ablaufzeit der Upload-URL

   • Upload-URLs erlöschen nach 1 Stunde
   • Wenn Sie eine abgelaufene URL-Fehlermeldung erhalten, führen Sie den Build-Befehl erneut aus

Tip

Sehr große Projekte können die Build-Zeitgrenze erreichen (siehe Bekannte EinschränkungenKontaktieren Sie den Support für Unternehmensoptionen.

”Build timeout nach 10 Minuten””

Symptome:

• Der Build überschreitet die maximale erlaubte Zeit
• Der Status zeigt timeout

Lösungen:

1. Optimieren Sie Abhängigkeiten

   • Entfernen Sie nicht benötigte npm-Pakete
   • Verwenden Sie npm prune --production vor dem Build

2. Überprüfen Sie Netzwerkprobleme im Build

   • Einige Abhängigkeiten laden während des Builds große Dateien herunter
   • Überlegen Sie, ob Sie mit einem Lock-File vorkacheln können

3. Überprüfen Sie native Abhängigkeiten

   # iOS - check Podfile for heavy dependencies
   cat ios/App/Podfile
   
   # Android - check build.gradle
   cat android/app/build.gradle

4. Kontaktieren Sie den Support

   • Wenn Ihr App legitim mehr Zeit benötigt
   • Wir können Grenzen für bestimmte Anwendungsfälle anpassen

Authentifizierungsprobleme

‚API-Schlüssel ungültig‘ oder ‚Unberechtigt‘

Symptome:

• Der Build scheitert sofort mit einer Authentifizierungsfehler
• 401 oder 403 Fehler

Lösungen:

1. Überprüfen Sie die API-Schlüssel auf Richtigkeit

   # Test with a simple command
   bunx @capgo/cli@latest app list

2. Überprüfen Sie die API-Schlüsselrechte

   • Der Schlüssel muss write oder all Überprüfen Sie im __CAPGO_KEEP_0__-Dashboard unter __CAPGO_KEEP_1__-Schlüsseln
   • Check in Capgo dashboard under API Keys

3. Die API-Schlüsselrechte

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or check your saved credentials file
   cat ~/.capgo-credentials/credentials.json   # global
   cat .capgo-credentials.json                 # local (--local)

4. Neu authentifizieren

   bunx @capgo/cli@latest login

”App not found” or “No permission for this app”

Abschnitt mit der Überschrift "Fehlermeldung: "Anwendung nicht gefunden" oder "Keine Berechtigung für diese Anwendung""

• Symptome:

Authentifizierung funktioniert, aber Anwendungsspezifischer Fehler

1. Lösungen:

   bunx @capgo/cli@latest app list

2. Überprüfen Sie, ob die App-ID übereinstimmt

   • Überprüfen capacitor.config.json appId
   • Stellen Sie sicher, dass die Befehlszeile die richtige App-ID verwendet

3. Überprüfen Sie die Zugriffsrechte der Organisation

   • Überprüfen Sie, ob Sie sich in der richtigen Organisation befinden
   • API muss Zugriff auf die Organisation der App haben

iOS-Bau-Probleme

„Code Signierung fehlgeschlagen“

Symptome:

• Der Build scheitert während der code-Signierungsphase
• Xcode meldet Fehler bei Zertifikaten oder Profilen

Lösungen:

1. Überprüfen Sie, ob das Zertifikatstyp mit dem Buildtyp übereinstimmt

   • Entwicklungsbuilds benötigen Entwicklungszertifikate
   • App Store Builds benötigen Verteilungszertifikate

2. Überprüfen Sie, ob Zertifikat und Profil übereinstimmen

   # Decode and inspect your certificate
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. Stellen Sie sicher, dass das Provisioning-Profild gültig ist

   • Überprüfen Sie die Ablaufzeit
   • Überprüfen Sie, ob es Ihren App-ID enthält
   • Bestätigen Sie, ob es das Zertifikat enthält

4. Regenerieren Sie die Anmeldeinformationen

   • Löschen Sie das alte Zertifikat/Profil
   • Erstellen Sie neue im Apple-Entwickler-Portal
   • Re-encode und aktualisieren Sie die Umgebungsvariablen

Provisioning-Profil enthält kein Signierungs-Zertifikat

Symptome:

• Xcode kann das Zertifikat im Profil nicht finden

Lösungen:

1. Herunterladen des neuesten Profils von Apple

   • Gehe zu Apple Developer → Zertifikate, IDs und Profile
   • Provisioning-Profil herunterladen
   • Stelle sicher, dass es dein Zertifikat enthält

2. Überprüfe, ob dein Zertifikat im Profil enthalten ist

   # Extract profile
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # View profile contents
   security cms -D -i profile.mobileprovision

3. Erstelle das Profil erneut mit dem richtigen Zertifikat

   • In der Apple Developer-Portal bearbeite das Profil
   • Stelle sicher, dass dein Verteilungs-Zertifikat ausgewählt ist
   • Herunterladen und erneut kodieren

„App Store Connect-Authentifizierung fehlgeschlagen“

Symptome:

• Die Upload zu TestFlight fehlt
• API-Schlüssel-Fehler

Lösungen:

1. Überprüfen Sie die API-Schlüssel-Zertifikate

   • Überprüfen Sie APPLE_KEY_ID (soll 10 Zeichen lang sein)
   • Überprüfen Sie APPLE_ISSUER_ID (soll im UUID-Format sein)
   • Überprüfen Sie, ob APPLE_KEY_CONTENT korrekt base64-codiert ist

2. Synchronisieren Sie die Uhr Ihres Computers

   • Die App Store Connect-Authentifizierung verwendet kurzlebige JWTs, die aus Ihrem lokalen Systemzeit generiert werden
   • Apple lehnt Token ab, die mehr als 20 Minuten in der Zukunft ablaufen, daher kann sogar ein kleiner Zeitdrift einen sonst gültigen Schlüssel zum Scheitern bringen
   • Öffnen Sie auf Windows Einstellungen > Zeit & Sprache > Datum & Uhrzeit und klicken Sie Synchronisieren Sie jetzt
   • Auf macOS öffnen Sie Systemeinstellungen > Allgemein > Datum & Uhrzeit und aktivieren Sie die automatische Zeit
   • Auf Linux überprüfen Sie timedatectl status und aktivieren Sie NTP, wenn erforderlich
   • Nach der Synchronisierung führen Sie den Capgo-Aufbau oder die Anmeldekommando erneut aus

   Siehe Apples Dokumentation zu Token-Generierung für API-Anfragen Dokumentation für die Regeldauer des App Store Connect-Tokens

3. Test API Schlüssel lokal

   # Decode key
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Test with fastlane (if installed)
   fastlane pilot list

4. Überprüfe die Berechtigungen für den API-Schlüssel

   • Der Schlüssel benötigt mindestens die Rolle „Entwickler“
   • Überprüfe in App Store Connect -> Benutzer und Zugriff -> Schlüssel

5. Stelle sicher, dass der Schlüssel nicht zurückgezogen ist

   • Überprüfe in App Store Connect
   • Erstelle einen neuen Schlüssel, wenn erforderlich

”Pod-Installationsfehler”

Symptome:

• Builds scheitern während der CocoaPods-Installation
• Podfile-Fehler

Lösungen:

1. Überprüfen Sie, ob Podfile.lock im Repository committet wurde

   git status ios/App/Podfile.lock

2. Testen Sie lokal eine pod install

   cd ios/App
   pod install

3. Überprüfen Sie nach inkompatiblen Pods

   • Überprüfen Sie die Podfile auf Versionskonflikte
   • Stellen Sie sicher, dass alle Pods Ihr iOS-Zielsystem unterstützen

4. Cache des Pods leeren

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Then commit new Podfile.lock

Android-Bauprobleme

„Falsches Keystore-Passwort“

Symptome:

• Der Build scheitert während der Signierung
• Gradle-Fehler über das Keystore

Lösungen:

1. Überprüfen Sie das Keystore-Passwort

   # Test keystore locally
   keytool -list -keystore my-release-key.keystore
   # Enter password when prompted

2. Überprüfe die Umgebungsvariablen

   # Ensure no extra spaces or special characters
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. Base64-Codierung überprüfen

   # Decode and test
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

Alias nicht gefunden

Symptome:

• Signierung fehlschlägt mit Aliasfehler

Lösungen:

1. Liste der Schlüsselkette-Bezeichner

   keytool -list -keystore my-release-key.keystore

2. Überprüfe, ob der Alias genau übereinstimmt

   • Der Alias ist case-sensitive
   • Überprüfe auf Tippfehler in KEYSTORE_KEY_ALIAS

3. Verwende den richtigen Alias aus der Schlüsselkette

   # Update environment variable to match
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

„Gradle-Build fehlgeschlagen“

Symptome:

• Allgemeine Gradle-Fehler
• Fehler bei der Kompilierung oder den Abhängigkeiten

Lösungen:

1. Testen Sie die lokale Erstellung zuerst

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Überprüfen Sie fehlende Abhängigkeiten

   • Überprüfen Sie die Dateien build.gradle
   • Stellen Sie sicher, dass alle Plugins in den Abhängigkeiten aufgeführt sind

3. Überprüfen Sie die Kompatibilität der Gradle-Version

   # Check gradle version
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Gradle-Cache löschen

   cd android
   ./gradlew clean
   rm -rf .gradle build

„Play Store-Upload fehlgeschlagen“

Symptome:

• Der Build ist erfolgreich, aber der Upload fehlschlägt
• Fehler bei der Dienstkonten-Konfiguration

Lösungen:

1. Dienstkonten-JSON-Datei überprüfen

   # Decode and check format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. Überprüfen Sie die Berechtigungen des Dienstkontos

   • Gehe zu Play Console → Setup → API Zugriff
   • Stellen Sie sicher, dass das Dienstkonto Zugriff auf Ihre App hat
   • Berechtigung „Release to testing tracks“ erteilen

3. Überprüfen Sie, ob die App in Play Console eingerichtet ist

   • Die App muss vorher in Play Console erstellt werden
   • Zumindest ein APK muss manuell ursprünglich hochgeladen werden

4. Überprüfen Sie, ob API aktiviert ist

   • Google Play Developer API muss aktiviert sein
   • Überprüfen Sie in Google Cloud Console

Allgemeine Probleme

”Job not found” or “Build status unavailable”

Symptome:

• Der Status der Auftragsausführung kann nicht überprüft werden
• Fehler bei der Job-ID

Lösungen:

1. Warten Sie einen Moment und versuchen Sie es erneut

   • Die Ausführung von Aufträgen kann einige Sekunden dauern

2. Überprüfen Sie, ob die Job-ID korrekt ist

   • Überprüfen Sie die Job-ID aus der Antwort der ersten Auftragsausführung

3. Überprüfen Sie, ob der Auftrag abgelaufen ist

   • Die Build-Daten sind 24 Stunden verfügbar

Projektsynchronisierung fehlgeschlagen

Symptome:

• Der Build scheitert, bevor die Kompilierung beginnt
• Fehlende Dateien

Lösungen:

1. Führen Sie Capacitor lokal synchron

   bunx cap sync

2. Stellen Sie sicher, dass alle native Dateien eingereicht wurden

   git status ios/ android/

3. Überprüfen Sie native Dateien, die von Git ignoriert werden

   • Überprüfen Sie .gitignore
   • Stellen Sie sicher, dass wichtige Konfigurationsdateien nicht ignoriert werden

"Der Build war erfolgreich, aber ich sehe keine Ausgabe"

Symptome:

• Der Build zeigt Erfolg, aber kein Downloadlink

Lösungen:

1. Überprüfen Sie die Build-Konfiguration

   • Die Artefakt-Speicherung mag nicht konfiguriert sein
   • Kontaktieren Sie den Support, wenn der Zugriff auf Artefakte für Ihren Build nicht verfügbar ist

2. Für die iOS-Testflug-Abgabe

   • Überprüfen Sie App Store Connect
   • Die Verarbeitung kann nach dem Hochladen 5-30 Minuten dauern

3. Für den Android Play Store

   • Überprüfen Sie Play Console → Testing → Internes Testen
   • Die Verarbeitung kann einige Minuten dauern

CI/CD-spezifische Probleme

GitHub Aktionen: “Befehl nicht gefunden”

Symptome:

• bunx @capgo/cli@latest … Fällt in CI mit “Befehl nicht gefunden” aus

Lösungen:

1. Stellen Sie Bun zuerst ein so bunx ist verfügbar:

   - uses: oven-sh/setup-bun@v2

2. Dann führen Sie den CLI aus — bunx Es wird es auf Anforderung geladen, keine globale Installation erforderlich:

   - run: bunx @capgo/cli@latest build request com.example.app --platform android

GitHub-Aktionen: „Geheime Daten nicht gefunden“

Symptome:

• Umgebungsvariablen sind in der Build leer

Lösungen:

1. Überprüfen Sie, ob Geheimnisse gesetzt sind

   • Gehe zu Repository-Einstellungen → Geheimnisse und Variablen → Aktionen
   • Fügen Sie alle erforderlichen Geheimnisse hinzu

2. Verwenden Sie die richtige Syntax

   env:
     CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

3. Überprüfen Sie, ob die Geheimnisnamen übereinstimmen

   • Die Namen sind case-sensitive
   • Keine Tippfehler in den Geheimnisverweisen

Mehr Hilfe erhalten

Aktivieren Sie die ausführliche Protokollierung

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

Baumeldung sammeln

Wenn Sie Unterstützung anfordern, fügen Sie bitte hinzu:

1. Verwendeter Build-Befehl

   bunx @capgo/cli@latest build request com.example.app --platform ios

2. Fehlermeldung (vollständiger Ausgabe)

3. Job-ID (aus der Build-Ausgabe)

4. Build-Protokolle (kopieren Sie die gesamte Terminal-Ausgabe)

5. Umgebungsinformationen

   node --version
   npm --version
   bunx @capgo/cli@latest --version

Kontaktieren Sie den Support

• Discord: Trifft euch in unserer Community
• E-Mail: support@capgo.app
• Navigation: Capgo Dokumentationen

Beschränkungen

aktuelle Einschränkungen:

• Höchstzeit für den Aufbau: 10 Minuten
• Höchstuploadgröße: ~500 MB
• iOS-Aufbauprozesse erfordern 24-Stunden-Mac-Mietverträge, der Aufbau auf einem Mac wird in die Warteschleife gelegt, um eine optimale Nutzung sicherzustellen
• Die Verfügbarkeit von Aufbauprodukten zum Herunterladen hängt von der Zieldestination und der Konfiguration der Artefakt-Speicherung ab

Diese Einschränkungen können aufgrund von Feedback angepasst werden

Einschränkungen aufgrund von Prescan

Capgo läuft einen lokalen Vorabscan vor dem Upload. Korrigieren Sie das gemeldete Ergebnis oder ignorieren Sie nur diese Überprüfung mit der ID:

npx @capgo/cli@latest build request <appId> --platform ios \
  --prescan-skip ios/capacitor-server-url-shipped

Siehe das vollständige Katalog: Vorabscans überprüfen.

Zusätzliche Ressourcen

• Einstieg - Anleitung für die erste Einrichtung
• iOS-Builds - iOS-spezifische Konfiguration
• Android Builds - Android-spezifische Konfiguration
• Prescan-Überprüfungen - Vollständige Liste der Vorbau-Überprüfungen und ignorierten Flags
• CLI Referenz - Vollständige Dokumentation der Befehle