Debuggen der PWA Kit Apps

Fehler und Leistungsengpässe lassen sich bei der Entwicklung einer Web-App nicht vermeiden. Mit PWA Kit können Sie diesen Problemen mit einer Reihe von Tools und Methoden für eine eingehende Untersuchung Ihrer App auf den Grund gehen.

Ersetzen Sie alle Platzhalter in dieser Anleitung durch tatsächliche Werte. Platzhalter haben das folgende Format: $PLACEHOLDER.

Bevor Sie die gezielteren Ratschläge dieser Anleitung befolgen, probieren Sie es zuerst mit diesen allgemeinen Schritten zur Fehlerbehebung:

• Vergewissern Sie sich, dass Sie eine unterstützte Version von Node verwenden (siehe Anleitung Erste Schritte), bevor Sie Ihren lokalen Entwicklungsserver starten.
• Bestätigen Sie, dass der Entwicklungsserver weiterhin läuft und der Port nicht von einem anderen Prozess genutzt wird.
• Bestätigen Sie nach einer Codeänderung, dass die Meldung HTTP development server listening im Terminal angezeigt wird, bevor Sie Ihren Browser neu laden.
• Achten Sie sowohl in der Browserkonsole als auch im Terminal auf Fehler.
• Suchen Sie unter Verwendung der Entwickler-Tools Ihres Browsers nach Netzwerk-Fehlermeldungen. (In den Chrome DevTools verwenden Sie dazu die Registerkarte Network (Netzwerk).)
• Führen Sie einen Code-Formatierer und einen Linter aus, um Syntax- und Tippfehler zu finden. Die Retail React App stellt Konfigurationsdateien sowohl für Prettier (Code-Formatierer) als auch für ESLint (Linter) bereit.
• Überprüfen Sie die Virenschutz- und Firewall-Einstellungen Ihres Computers auf alle Probleme, die die Ausführung von Code verhindern oder Netzwerkanfragen blockieren.
• Identifizieren und analysieren Sie Probleme mit dem Profiler der Chrome DevTools. Weitere Informationen finden Sie in dieser Anleitung von Google: Analyze Runtime Performance (Laufzeit-Performance analysieren). Sie können auch die Chrome-Erweiterung React Developer Tools installieren, um eine zusätzliche Profiler-Registerkarte mit ähnlichen Informationen auf Komponentenebene zu erhalten.

Es gibt zwei spezielle Abfrageparameter, die Sie allen von Ihrer Commerce App bereitgestellten URLs hinzufügen können, um Probleme mit serverseitigem Code leichter zu debuggen.

Der Abfrageparameter __server_only stoppt die Hydration, sodass die Seite in Ihrem Browser genauso aussieht wie nach dem serverseitigen Rendering. Diese serverseitig gerenderte Seitenversion unterstützt Sie nicht nur bei der Behebung von beim serverseitigen Rendering aufgetretenen Fehlern, sondern auch bei der Suchmaschinenoptimierung, da Suchmaschinen diese Version der Seite durchsuchen.

Der Abfrageparameter __pretty_print formatiert das Objekt __PRELOADED_STATE__, damit es einfacher zu lesen ist. Dieses Objekt liefert einen Snapshot des Zustands Ihrer Anwendung vor Beginn der Hydration. So können Sie beim Debugging feststellen, ob die erwarteten Werte verwendet werden. Sie können sich die Inhalte des Objekts anzeigen lassen, indem Sie Ihre App laden, den Seitenquelltext aufrufen und nach __PRELOADED_STATE__ suchen.

Das Objekt __PRELOADED_STATE__ befindet sich in einem <script>-Tag im HTML-Seitenquelltext, das beim serverseitigen Start Ihrer App angefordert wurde. Das Objekt __PRELOADED_STATE__ enthält von der Funktion getProps zurückgegebene serialisierte Werte (einschließlich der Versionen von getProps, die an die _app-Komponente und die Seitenkomponente angehängt sind).

Standardmäßig zeigt der App-Server Konsolenmeldungen im Terminal an. Es ist jedoch nicht möglich, die Ausführung des Codes zu beobachten. Dies kann das Debuggen des Codes, der die Seiten serverseitig (oder auf Ihrem lokalen Rechner) rendert, erschweren.

Für erweitertes Debugging können Sie Ihren lokalen Entwicklungsserver über einen alternativen Befehl starten, der einen Inspektionsprozess in Node ausführt, an den sich ein Debugger anhängen kann. (Nähere Details finden Sie in der Node-Dokumentation.)

Sie können den in vielen gängigen Browsern und Texteditoren inbegriffenen Debugger an den Node-Inspektionsprozess anhängen. Hier finden Sie die entsprechenden Anleitungen für Google Chrome und Visual Studio Code.

1. Öffnen Sie ein Terminal.
2. Rufen Sie Ihr Projektverzeichnis auf.
3. Starten Sie Ihren lokalen Dev-Server mit npm run start:inspect.
4. Zur Bestätigung, dass der Debugger zugeschaltet ist, sollte in der Terminalausgabe die Meldung "Debugger listening" (Debugger hört zu) angezeigt werden.
5. Öffnen Sie Chrome und geben Sie die URL chrome://inspect ein.
6. Klicken Sie auf Open dedicated DevTools for Node (Dedizierte DevTools für Node öffnen).
7. DevTools wird in einem neuen Fenster geöffnet.
8. Zur Bestätigung, dass der Debugger angehängt ist, sollte in der Terminalausgabe die Meldung "Debugger attached" (Debugger angehängt) angezeigt werden.
9. Legen Sie Umschaltpunkte fest, fügen Sie debugger-Anweisungen hinzu und so weiter.
10. Laden Sie eine Seite von Ihrem lokalen Entwicklungsserver in Chrome.
11. Verwenden Sie das dedizierte Fenster für das Debugging.

Jetzt können Sie die Ausführung Ihres serverseitigen Codes nachverfolgen.

Um mehr über das Debuggen mit Umschaltpunkten in den DevTools zu erfahren, lesen Sie diese Anleitung von Google: Debug JavaScript (JavaScript debuggen).

1. Öffnen Sie Ihre Projektdateien in Visual Studio Code.
2. Klicken Sie in der Menüleiste auf Terminal > New Terminal (Terminal > Neues Terminal).
3. Starten Sie Ihren lokalen Dev-Server mit npm run start:inspect.
4. Öffnen Sie die Befehlspalette. Tastenkürzel für Windows: Ctrl + Shift + P. Tastenkürzel für Mac: Command + Shift + P.
5. Geben Sie den folgenden Befehl ein: “Debug: Attach to Node Process” (Debuggen: An Node-Prozess anhängen).
6. Eine Liste mit den Node-Prozessen wird angezeigt. Wählen Sie den ersten Prozess in der Liste aus.
7. Zur Bestätigung, dass der Debugger angehängt ist, sollte in der Terminalausgabe die Meldung "Debugger attached" (Debugger angehängt) angezeigt werden.
8. Legen Sie Umschaltpunkte fest, fügen Sie Debugger-Anweisungen hinzu und so weiter.
9. Laden Sie eine Seite von Ihrem lokalen Entwicklungsserver in Ihren Webbrowser.
10. Verwenden Sie fürs Debuggen den in Visual Studio Code integrierten Debugger.

Jetzt können Sie die Ausführung Ihres serverseitigen Codes in Visual Studio Code nachverfolgen.

Für das Debugging von Code, der in Managed Runtime (MRT) bereitgestellt wird, können Sie drei Methoden verwenden:

• Quellzuordnungen zur genauen Bestimmung, wo Fehler aufgetreten sind
• Verfolgen von Logs zum Debuggen von Echtzeit-Problemen oder Fehlern in kleineren Umgebungen
• Log Center für Production-Umgebungen, das leistungsstarke Funktionalitäten für die Suche und Aufbewahrung bietet

Verwenden Sie Quellzuordnungen, um server- oder clientseitige Fehler zu identifizieren. Quellzuordnungen bieten ein einfaches Error Stack Trace, das angibt, wo ein Fehler aufgetreten ist. Der Stack-Trace identifiziert z. B. die Datei- und Zeilennummer, in der der Fehler aufgetreten ist, um die Fehlerbehebung zu erleichtern.

Um Quellzuordnungen verwenden zu können, müssen Sie Ihre Website mit PWA Kit Version 3.4.x oder höher erstellen. Wenn Sie über eine frühere Version verfügen, aktualisieren Sie Ihr Projekt auf PWA Kit 3.4.x.

Sie haben zwei Möglichkeiten, Quellzuordnungen zu aktivieren: mit Runtime Admin oder mit der Managed Runtime API.

Verwendung von Runtime Admin

1. Melden Sie sich bei Runtime Admin an.
2. Klicken Sie auf Ihr Projekt.
3. Klicken Sie auf eine Umgebung.
4. Klicken Sie auf Umgebungseinstellungen.
5. Klicken Sie im Abschnitt Advanced (Erweitert) auf Edit (Bearbeiten).
6. Aktivieren Sie Quellzuordnungen.
7. Klicken Sie oben im Abschnitt "Erweitert" auf Aktualisieren.
8. Warten Sie, bis die erneute Bereitstellung des Bündels abgeschlossen ist.

Verwendung der Managed Runtime API

Rufen Sie den projects_target_partial_update API-Endpunkt auf und legen Sie den Wert enable_source_maps auf true fest. Dadurch wird die Managed Runtime-Umgebungsvariable NODE_OPTIONS in Ihrer Umgebung mit --enable-source-mapskonfiguriert und das Bündel erneut bereitgestellt.

1. Wenn Sie das Projekt erstellen, generieren Sie die Datei ssr.js.map mithilfe der folgenden lokalen Umgebungsvariablen: PWA_KIT_SSR_SOURCE_MAP=true.

2. Stellen Sie Ihr Bündel in Managed Runtime bereit.

Nachdem Sie Quellzuordnungen aktiviert und hochgeladen haben, können Sie sie das Verfolgen von Logs (Log Tailing) in Managed Runtime verwenden.

Die Verwendung von Quellzuordnungen kann zu Leistungsproblemen führen. Zum Beispiel gibt es Latenzzeiten, wenn auf error.stack zugegriffen wird. Wenn Sie also in Ihren Code console.error(e) einfügen, kann dies Ihre Website verlangsamen.

• Neue Nicht-Production-Umgebungen: enable_source_maps ist auf true festgelegt.
• Neue Production-Umgebungen: enable_source_maps ist auf false festgelegt. Dieses Verhalten trägt dazu bei, potenzielle Leistungseinbußen zu vermeiden, die bei aktivierter Quellzuordnungsfunktionalität auftreten können.
• Alle bereits vorhandenen Umgebungen: enable_source_maps ist auf false festgelegt.

Für auf Managed Runtime bereitgestellte Anwendungen wird Remote-Debugging nicht unterstützt. Sie können jedoch Logs für alle Managed Runtime-Umgebungen in Echtzeit verfolgen, um eventuelle serverseitige Fehler zu diagnostizieren.

Für die Verfolgung von Logs über die Befehlszeile gibt es zwei Möglichkeiten.

Wenn Sie innerhalb eines PWA Kit-Projekts arbeiten, das mit einer Version ab 2.4.1 generiert wurde, können Sie Folgendes tun:

• Hilfe für den Logs-Befehl anzeigen: npm run tail-logs -- --help
• Logs für ein bestimmtes Projekt und eine bestimmte Umgebung verfolgen: npm run tail-logs -- --environment $ENV_ID

Wenn Sie außerhalb eines PWA Kit-Projekts arbeiten oder ein Projekt haben, das mit einer Version vor 2.4.1 generiert wurde, können Sie mit npx Folgendes tun:

• Hilfe für den Logs-Befehl anzeigen: npx @salesforce/pwa-kit-dev tail-logs --help
• Logs für eine bestimmte Umgebungs- und Projekt-ID in Echtzeit verfolgen: npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

Bei der Verfolgung von Protokollen sind die folgenden Einschränkungen zu beachten:

• Alle Log Tailing-Sessions werden nach 60 Minuten beendet.
• Jede Umgebung kann – unabhängig von der Anzahl der aktiven Benutzer – maximal 100 aktive Log Tailing-Sessions gleichzeitig unterstützen.
• Für das Log Tailing sind Entwickler- oder Administratorrechte für das Managed Runtime-Projekt erforderlich.

Verwenden Sie Log Center, um Fehler zu beheben, wenn Sie eine Website mit PWA Kit erstellt haben oder über eine B2C Commerce-Instanz verfügen. Log Center:

• Bietet einen zentralen Speicherort für den Zugriff auf Logs von Managed Runtime (MRT) und Ihrer B2C Commerce-Instanz. Erstellen Sie Korrelationen zwischen Vorgängen in Ihrer MRT-Umgebung und B2C Commerce-Instanz.
• Ermöglicht das Durchsuchen und Filtern vieler historischer Logs. Sie können weitere Informationen darüber erhalten, was in der Production passiert ist, um Probleme schneller zu untersuchen und zu beheben.

Diese Anleitung beschreibt das Debugging von Websites, die mit PWA Kit erstellt wurden. Informationen zur Verwendung von Log Center mit Ihrer B2C Commerce-Instanz finden Sie unter Zentralisiertes Log Center.

Um auf MRT-Log für eine Umgebung in Log Center zuzugreifen, müssen Sie zunächst folgende Schritte ausführen:

1. Sie verfügen über die Rolle Log Center-Benutzer in Account Manager. Überprüfen Sie dafür Ihre Rolle in Account Manager. Wenn Sie die Rolle nicht haben, bitten Sie Ihren Account Manager-Administrator, Ihnen Zugriff zu gewähren. Weitere Informationen finden Sie unter Managing Account Manager for Salesforce B2C Commerce Users (Verwalten des Account Manager für Salesforce B2C Commerce-Benutzer).

2. Richten Sie die Umgebung wie folgt ein:

   a. Markieren Sie die Umgebung als Production-Umgebung. Weitere Informationen finden Sie unter Details und Einschränkungen zu Production-Umgebungen.

   b. Wählen Sie eine Commerce Cloud-Instanz (B2C Commerce) aus, um eine Verbindung mit der Umgebung herzustellen.

   c. Fügen Sie mindestens eine Website-ID hinzu, die der Umgebung zugeordnet werden soll.

Nachdem Sie die Voraussetzungen erfüllt haben, gehen Sie wie folgt vor, um MRT Logs in Log Center anzuzeigen:

1. Starten Sie Log Center.
2. Wählen Sie eine Region aus.
3. Wählen Sie ein Realm aus. Sollten Sie Ihre Realm-ID nicht kennen, fragen Sie Ihren Kundenbetreuer oder Customer Success Manager (CSM) danach.
4. Klicken Sie auf Show filtered results (Gefilterte Ergebnisse anzeigen).
5. Klicken Sie auf Search > Current Search (Suche > aktuelle Suche).
6. Wählen Sie unter Servicetyp die Option mrt aus.
7. Wählen Sie unter Host die Production-Umgebung aus, deren MRT-Logs Sie anzeigen möchten. Das Host-Format ist $PROJECT.$ENVIRONMENT. Bei mehreren MRT-Production-Umgebungen können auch mehrere MRT-Host-Namen angezeigt werden.
8. Zeigen Sie die MRT Logs an.

Informationen zu Log-Ebenen und Log-Volumen in Log Center finden Sie unter Configuration for Administrators (Konfiguration für Administratoren).