Fehlerbehebung

Hier findest du häufige Probleme bei der Nutzung von Capgo und wie du sie löst.

🚀 Brauchst du Expertenhilfe?

Hängst du bei einem komplexen Problem fest? Unser Expertenteam hilft dir gerne weiter! Hol dir persönlichen Support, code Reviews und maßgeschneiderte Lösungen für deine Anforderungen.

Professionellen Support erhalten

Upload-Fehler

Falls dein Bundle-Upload fehlschlägt, prüfe Folgendes:

• Ob deine App-ID in capacitor.config.ts mit deiner App im Capgo Dashboard übereinstimmt
• Ob du den Upload-Befehl im Root deines Capacitor Projekts ausführst
• Ob deine Web-Assets gebaut und aktuell sind

Erweiterte Upload-Optionen

Das Capgo CLI bietet einige zusätzliche Flags, die bei häufigen Upload-Problemen helfen:

• --tus: Nutzt das das tus resumable upload protocol für zuverlässigere Uploads großer Bundles oder bei schlechter Netzwerkverbindung. Wenn Ihr Bundle größer als 10 MB ist oder Sie eine instabile Verbindung haben, sollten Sie Folgendes verwenden: --tus:

  npx @capgo/cli@latest bundle upload --tus

• --package-json und --node-modules: Gibt Capgo an, wo Ihr Root-Verzeichnis zu finden ist package.json und node_modules wenn Ihre App eine nicht standardmäßige Struktur wie ein Monorepo oder einen npm-Workspace verwendet. Übergeben Sie den Pfad zum Root-Verzeichnis package.json und --node_modules Pfad:

  npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules

  Capgo benötigt diese Informationen, um die Abhängigkeiten deiner App korrekt zu bundlen.

Du kannst diese Flags mit anderen Optionen kombinieren, wie zum Beispiel --channel je nach Bedarf. Siehe die Capgo CLI Dokumentation für alle Details zu den verfügbaren Upload-Optionen.

Falls du weiterhin Probleme beim Upload hast, wende dich an Capgo Support für weitere Unterstützung.

Updates debuggen

Wenn du Probleme mit Live Updates hast, ist der Debug-Befehl von Capgo ein hilfreiches Tool zur Fehlersuche. So nutzt du ihn:

1. Führe den folgenden Befehl in deinem Projektverzeichnis aus:

   npx @capgo/cli@latest app debug

2. Starte deine App auf einem Gerät oder Emulator und führe die Aktion aus, die ein Update auslösen soll (z. B. das erneute Öffnen der App nach dem Upload eines neuen Bundles).

3. Beobachte die Ausgabe des Debug-Befehls. Er protokolliert Informationen zum Update-Prozess, einschließlich:

   • Wann die App nach einem Update sucht
   • Ob ein Update gefunden wurde und um welche Version es sich handelt
   • Fortschritt des Downloads und der Installation des Updates
   • Etwaige Fehler, die während des Update-Prozesses auftreten

4. Nutze die Debug-Logs, um die Fehlerquelle zu identifizieren. Zum Beispiel:

   • Falls kein Update gefunden wird, prüfe noch einmal, ob dein Bundle erfolgreich hochgeladen wurde und die App für den richtigen Channel konfiguriert ist.
   • Falls das Update heruntergeladen, aber nicht installiert wird, stelle sicher, dass du CapacitorUpdater.notifyAppReady() und dass die App vollständig geschlossen und neu geöffnet wurde.
   • Wenn du eine Fehlermeldung siehst, suche den spezifischen Fehler in den Capgo-Dokumenten nach oder wende dich an den Support.

Der Debug-Befehl ist besonders nützlich, um Probleme beim Download und der Installation von Updates zu identifizieren. Wenn die Logs zeigen, dass die erwartete Update-Version gefunden, aber nicht angewendet wurde, konzentriere dich auf die Schritte nach dem Download.

Debugging mit nativen Logs

Zusätzlich zum Capgo-Debug-Befehl können die nativen Logs auf Android, iOS und Electron wertvolle Troubleshooting-Informationen liefern, insbesondere für Probleme auf der nativen Seite des Update-Prozesses.

Android-Logs

So greifst du auf die Android-Logs zu:

1. Verbinde dein Gerät oder starte deinen Emulator
2. Öffne Android Studio und wähle „Ansicht > Tool-Fenster > Logcat“
3. Filtere im Logcat-Fenster die Logs auf den Prozess deiner App, indem du ihn aus dem Dropdown oben auswählst
4. Suche nach Zeilen, die Folgendes enthalten Capgo um die SDK Logs zu finden

Alternativ kannst du die adb logcat Befehl und nach folgendem greppen: Capgo um die Logs zu filtern.

Das Capgo SDK loggt wichtige Ereignisse während des Update-Prozesses, wie zum Beispiel:

• Wenn ein Update-Check gestartet wird
• Ob ein Update gefunden wurde und um welche Version es sich handelt
• Wenn der Update-Download startet und abgeschlossen wird
• Wenn die Update-Installation ausgelöst wird
• Alle Fehler, die während der nativen Update-Schritte auftreten

Häufige Android-spezifische Probleme, die in den Logs auftauchen, sind:

• Netzwerkprobleme, die den Update-Download verhindern
• Dateiberechtigungsfehler beim Speichern oder Lesen des Update-Bundles
• Kein Speicherplatz mehr für das Update-Bundle
• App startet nach der Installation des Updates nicht neu

iOS-Logs

So greifen Sie auf die iOS-Logs zu:

1. Verbinden Sie Ihr Gerät oder starten Sie den Simulator
2. Öffnen Sie Xcode und gehen Sie zu „Fenster > Geräte und Simulatoren“
3. Wählen Sie Ihr Gerät aus und klicken Sie auf „Konsole öffnen“
4. Suchen Sie in der Konsolenausgabe nach Zeilen, die Folgendes enthalten: Capgo um die SDK Logs zu finden

Du kannst auch die log stream Befehl im Terminal ausführen und nach ... greppen Capgo um die Logs zu filtern.

Ähnlich wie bei Android loggt das Capgo SDK wichtige Events auf der iOS-Seite:

• Start und Ergebnis des Update-Checks
• Download-Start, Fortschritt und Abschluss
• Trigger und Ergebnis der Installation
• Fehler während des nativen Update-Prozesses

iOS-spezifische Probleme, die du in den Logs erkennen kannst:

• SSL-Zertifikatsprobleme beim Download des Updates
• App Transport Security blockiert den Update-Download
• Nicht genügend Speicherplatz für das Update-Bundle
• Fehler beim korrekten Entpacken oder Anwenden des Update-Bundles

Electron-Logs

Bei Electron-Apps die Ausgabe von Main- und Renderer-Prozess prüfen:

1. Electron-App über das Terminal mit dem üblichen Startbefehl ausführen (z. B. bun run electron:dev oder bun run electron:serve) und die Terminalausgabe auf Startvorgang, Update-Checks und Netzwerkfehler beobachten.
2. Öffnen Sie DevTools im Renderer-Fenster (Ansicht → Entwicklerwerkzeuge umschalten) und untersuchen Sie die Konsolen-Logs sowie fehlgeschlagene Netzwerk-Anfragen, während Sie den Update-Flow nachstellen.
3. Bei gepackten Apps die OS-Log-Tools auf Crashes oder Startfehler prüfen:
   • macOS: öffnen Console.app und nach dem App-Namen filtern
   • Windows: öffnen Event-Viewer → Windows-Protokolle → Anwendung
   • Linux: nutze deinen Desktop-Logviewer oder journalctl für deinen App-Prozess

Vergleiche beim Debugging von Updates die Meldungen aus den Main-Prozess- und Renderer-Prozess-Logs, um Electron-Bootstrap-Probleme von Problemen im Capgo Update-Lifecycle zu unterscheiden.

Plattformübergreifend bieten die nativen Logs einen tiefergehenden Einblick in den Update-Prozess und mehr Details zur nativen Implementierung. Sie sind besonders hilfreich, um Probleme zu erkennen, die außerhalb der Capgo JavaScript-Schicht auftreten.

Bei der Fehlersuche an einem kniffligen live update-Problem solltest du sowohl die Capgo Debug-Logs als auch die nativen Logs erfassen, um ein vollständiges Bild zu bekommen. Beide Logs zusammen geben dir die beste Chance, das Problem zu identifizieren und zu lösen.

Updates werden nicht angewendet

Wenn du ein Bundle hochgeladen hast, aber die Änderungen auf deinem Gerät nicht siehst:

• Stelle sicher, dass du CapacitorUpdater.notifyAppReady() in deiner App code aufgerufen hast, wie in der Quickstart
• Prüfe, ob dein Gerät mit dem Internet verbunden ist und ob die Capgo Debug-Logs zeigen, dass das Update heruntergeladen wurde
• Schließe die App vollständig und starte sie neu, da Updates erst beim Kaltstart angewendet werden
• Suche in den nativen Logs nach Fehlern, die auf ein Problem beim Anwenden des Updates hindeuten könnten

Siehe dazu den Leitfaden zum Deployment von Live Updates für weitere Details zum Update-Prozess. Falls du weiterhin nicht weiterkommst, nutze den npx @capgo/cli@latest app debug Befehl und die nativen Logs, um besser zu sehen, was passiert.

Häufige Fehlercodes bei Updates

Wenn deine Logs Backend-Fehler wie diese zeigen: disable_auto_update_to_major, semver_error, oder cannot_update_via_private_channel, nutze dafür den eigenen Guide:

• Häufige Update-Probleme

Dort steht, was die einzelnen gängigen code bedeuten, warum sie auftreten und wie du sie behebst.

SDK Installation

Wenn du Probleme bei der Installation des Capgo SDK hast, achte darauf:

• Deine App eine unterstützte Version von Capacitor nutzt (4.0 oder neuer)
• You’ve followed the Quickstart Schritt für Schritt, einschließlich der Synchronisierung Ihrer App nach der Installation von SDK

CI/CD-Integration

Bei Problemen mit dem Auslösen von Capgo-Uploads aus Ihrer CI/CD-Pipeline:

• Prüfen Sie, ob Ihr Capgo-Authtoken korrekt eingerichtet ist
• Stellen Sie sicher, dass Sie den Upload-Befehl ausführen, nachdem Ihre Web-Assets gebaut wurden
• Prüfen Sie, ob der Upload-Befehl den richtigen Channel-Namen für Ihre Zielumgebung verwendet

Siehe den CI/CD-Integration Dokumentation für weitere Troubleshooting-Tipps. Sie können auch den npx @capgo/cli@latest app debug Befehl verwenden, um zu bestätigen, ob Ihre per CI/CD ausgelösten Updates von der App empfangen werden.

Weiter von Troubleshooting

Wenn du es nutzt Fehlerbehebung um Speicher- und Dateiverwaltung zu planen, verbinde es mit @capgo/capacitor-data-storage-sqlite für die Implementierungsdetails in @capgo/capacitor-data-storage-sqlite, Mit @capgo/capacitor-data-storage-sqlite für die native Funktionalität in „@capgo/capacitor-data-storage-sqlite verwenden“, @capgo/capacitor-file für das Implementierungsdetail in @capgo/capacitor-file, @capgo/capacitor-file verwenden für die native Funktion in „@capgo/capacitor-file verwenden“ und @capgo/capacitor-uploader für das Implementierungsdetail in @capgo/capacitor-uploader.