Node.js Debugging

Dieser Leitfaden hilft Ihnen beim Einstieg in das Debugging Ihrer Node.js-Anwendungen und -Skripte.

Inspector aktivieren

Wenn ein Node.js-Prozess mit dem Schalter --inspect gestartet wird, wartet er auf einen Debugging-Client. Standardmäßig lauscht er auf Host und Port 127.0.0.1:9229. Jedem Prozess wird auch eine eindeutige UUID zugewiesen.

Inspector-Clients müssen Hostadresse, Port und UUID kennen und angeben, um sich zu verbinden. Eine vollständige URL sieht etwa so aus: ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.

Node.js beginnt auch mit dem Lauschen auf Debugging-Nachrichten, wenn es ein SIGUSR1-Signal empfängt. (SIGUSR1 ist unter Windows nicht verfügbar.) In Node.js 7 und früher aktiviert dies die Legacy-Debugger-API. In Node.js 8 und später wird die Inspector-API aktiviert.

Sicherheitsauswirkungen

Da der Debugger vollen Zugriff auf die Node.js-Ausführungsumgebung hat, kann ein böswilliger Akteur, der sich mit diesem Port verbinden kann, möglicherweise willkürlichen Code im Namen des Node.js-Prozesses ausführen. Es ist wichtig, die Sicherheitsauswirkungen der Offenlegung des Debugger-Ports in öffentlichen und privaten Netzwerken zu verstehen.

Die öffentliche Freigabe des Debug-Ports ist unsicher

Wenn der Debugger an eine öffentliche IP-Adresse oder an 0.0.0.0 gebunden ist, können sich alle Clients, die Ihre IP-Adresse erreichen können, ohne Einschränkung mit dem Debugger verbinden und beliebigen Code ausführen.

Standardmäßig bindet node --inspect an 127.0.0.1. Sie müssen explizit eine öffentliche IP-Adresse oder 0.0.0.0 usw. angeben, wenn Sie externe Verbindungen zum Debugger zulassen möchten. Dies kann Sie einer potenziell erheblichen Sicherheitsbedrohung aussetzen. Wir empfehlen Ihnen, geeignete Firewalls und Zugriffskontrollen einzurichten, um eine Sicherheitsgefährdung zu vermeiden.

Im Abschnitt „Remote-Debugging-Szenarien aktivieren“ finden Sie einige Ratschläge, wie Sie Remote-Debugger-Clients sicher verbinden können.

Lokale Anwendungen haben vollen Zugriff auf den Inspector

Auch wenn Sie den Inspector-Port an 127.0.0.1 (Standard) binden, haben alle Anwendungen, die lokal auf Ihrem Rechner laufen, uneingeschränkten Zugriff. Dies ist so konzipiert, dass lokale Debugger sich bequem verbinden können.

Browser, WebSockets und Same-Origin-Policy

Websites, die in einem Webbrowser geöffnet werden, können im Rahmen des Browser-Sicherheitsmodells WebSocket- und HTTP-Anfragen stellen. Eine anfängliche HTTP-Verbindung ist erforderlich, um eine eindeutige Debugger-Sitzungs-ID zu erhalten. Die Same-Origin-Policy verhindert, dass Websites diese HTTP-Verbindung herstellen können. Für zusätzliche Sicherheit gegen DNS-Rebinding-Angriffe verifiziert Node.js, dass die "Host"-Header für die Verbindung entweder eine IP-Adresse oder präzise localhost angeben.

Diese Sicherheitsrichtlinien verbieten die Verbindung zu einem Remote-Debug-Server durch Angabe des Hostnamens. Sie können diese Einschränkung umgehen, indem Sie entweder die IP-Adresse angeben oder SSH-Tunnel verwenden, wie unten beschrieben.

Inspector-Clients

Ein minimaler CLI-Debugger ist mit node inspect myscript.js verfügbar. Mehrere kommerzielle und Open-Source-Tools können sich ebenfalls mit dem Node.js Inspector verbinden.

Chrome DevTools 55+, Microsoft Edge

• Option 1: Öffnen Sie chrome://inspect in einem Chromium-basierten Browser oder edge://inspect in Edge. Klicken Sie auf die Schaltfläche "Konfigurieren" und stellen Sie sicher, dass Ihr Zielhost und -port aufgeführt sind.
• Option 2: Kopieren Sie die devtoolsFrontendUrl aus der Ausgabe von /json/list (siehe oben) oder dem --inspect-Hinweistext und fügen Sie sie in Chrome ein.

Weitere Informationen finden Sie unter https://github.com/ChromeDevTools/devtools-frontend und https://www.microsoftedgeinsider.com.

Visual Studio Code 1.10+

• Klicken Sie im Debug-Panel auf das Einstellungs-Symbol, um .vscode/launch.json zu öffnen. Wählen Sie für die Erstkonfiguration "Node.js" aus.

Weitere Informationen finden Sie unter https://github.com/microsoft/vscode.

JetBrains WebStorm und andere JetBrains IDEs

• Erstellen Sie eine neue Node.js-Debug-Konfiguration und klicken Sie auf "Debuggen". --inspect wird standardmäßig für Node.js 7+ verwendet. Um dies zu deaktivieren, deaktivieren Sie js.debugger.node.use.inspect in der IDE-Registry. Weitere Informationen zum Ausführen und Debuggen von Node.js in WebStorm und anderen JetBrains IDEs finden Sie in der WebStorm Online-Hilfe.

chrome-remote-interface

• Bibliothek zur Vereinfachung von Verbindungen zu Inspector Protocol-Endpunkten. Weitere Informationen finden Sie unter https://github.com/cyrus-and/chrome-remote-interface.

Gitpod

• Starten Sie eine Node.js-Debugkonfiguration aus der Ansicht Debug oder drücken Sie F5. Detaillierte Anweisungen

Weitere Informationen finden Sie unter https://www.gitpod.io.

Eclipse IDE mit der Eclipse Wild Web Developer-Erweiterung

• Wählen Sie in einer .js-Datei Debug As... > Node program oder erstellen Sie eine Debugkonfiguration, um den Debugger an eine laufende Node.js-Anwendung anzuhängen (bereits mit --inspect gestartet).

Weitere Informationen finden Sie unter https://eclipse.org/eclipseide.

Befehlszeilenoptionen

Die folgende Tabelle listet die Auswirkungen verschiedener Laufzeit-Flags auf das Debugging auf:

Flag	Bedeutung
--inspect	Aktiviert das Debugging mit dem Node.js-Inspector. Hören Sie auf der Standardadresse und dem Standardport (127.0.0.1:9229)
--inspect-brk	Aktiviert das Debugging mit dem Node.js-Inspector. Hören Sie auf der Standardadresse und dem Standardport (127.0.0.1:9229); Unterbrechen, bevor der Benutzercode startet
--inspect=[host:port]	Aktiviert den Inspector-Agenten; Bindet an die Adresse oder den Hostnamen host (Standard: 127.0.0.1); Hört auf dem Port port (Standard: 9229)
--inspect-brk=[host:port]	Aktiviert den Inspector-Agenten; Bindet an die Adresse oder den Hostnamen host (Standard: 127.0.0.1); Hört auf dem Port port (Standard: 9229); Unterbrechen, bevor der Benutzercode startet
--inspect-wait	Aktiviert den Inspector-Agenten; Hören Sie auf der Standardadresse und dem Standardport (127.0.0.1:9229); Warten Sie, bis der Debugger angehängt wird.
--inspect-wait=[host:port]	Aktiviert den Inspector-Agenten; Bindet an die Adresse oder den Hostnamen host (Standard: 127.0.0.1); Hört auf dem Port port (Standard: 9229); Warten Sie, bis der Debugger angehängt wird.
node inspect script.js	Starten Sie einen Kindprozess, um das Skript des Benutzers mit dem Flag --inspect auszuführen, und verwenden Sie den Hauptprozess, um den CLI-Debugger auszuführen.
node inspect --port=xxxx script.js	Starten Sie einen Kindprozess, um das Skript des Benutzers mit dem Flag --inspect auszuführen, und verwenden Sie den Hauptprozess, um den CLI-Debugger auszuführen. Hört auf dem Port port (Standard: 9229)

Remote-Debugging-Szenarien aktivieren

Wir empfehlen, dass der Debugger niemals auf einer öffentlichen IP-Adresse lauscht. Wenn Sie Remote-Debugging-Verbindungen zulassen müssen, empfehlen wir stattdessen die Verwendung von SSH-Tunneln. Das folgende Beispiel dient nur zur Veranschaulichung. Bitte verstehen Sie das Sicherheitsrisiko, das mit der Gewährung von Fernzugriff auf einen privilegierten Dienst verbunden ist, bevor Sie fortfahren.

Nehmen wir an, Sie betreiben Node.js auf einem Remote-Rechner, remote.example.com, den Sie debuggen möchten. Auf diesem Rechner sollten Sie den Node-Prozess mit dem Inspector starten, der nur auf localhost lauscht (die Standardeinstellung).

node --inspect app.js

Nun können Sie auf Ihrem lokalen Rechner, von dem aus Sie eine Debug-Client-Verbindung initiieren möchten, einen SSH-Tunnel einrichten:

ssh -L 9225:localhost:9229 remote.example.com

Dies startet eine SSH-Tunnel-Sitzung, bei der eine Verbindung zu Port 9221 auf Ihrem lokalen Rechner an Port 9229 auf remote.example.com weitergeleitet wird. Sie können nun einen Debugger wie Chrome DevTools oder Visual Studio Code an localhost:9221 anhängen, der in der Lage sein sollte, so zu debuggen, als ob die Node.js-Anwendung lokal laufen würde.

Legacy-Debugger

Der Legacy-Debugger ist seit Node.js 7.7.0 als veraltet markiert. Bitte verwenden Sie stattdessen --inspect und Inspector.

Wenn Node.js in Version 7 und früher mit den Schaltern --debug oder --debug-brk gestartet wird, lauscht es auf Debugging-Befehle, die durch das eingestellte V8-Debugging-Protokoll auf einem TCP-Port, standardmäßig 5858, definiert sind. Jeder Debugger-Client, der dieses Protokoll spricht, kann sich mit dem laufenden Prozess verbinden und ihn debuggen; ein paar beliebte sind unten aufgeführt.

Das V8-Debugging-Protokoll wird nicht mehr gepflegt oder dokumentiert.

Eingebauter Debugger

Starten Sie node debug script_name.js, um Ihr Skript unter dem eingebauten Befehlszeilen-Debugger zu starten. Ihr Skript startet in einem anderen Node.js-Prozess, der mit der Option --debug-brk gestartet wurde, und der anfängliche Node.js-Prozess führt das Skript _debugger.js aus und verbindet sich mit Ihrem Ziel. Weitere Informationen finden Sie in den Dokumenten.

node-inspector

Debuggen Sie Ihre Node.js-App mit den Chrome DevTools, indem Sie einen Zwischenprozess verwenden, der das im Chromium verwendete Inspector-Protokoll in das in Node.js verwendete V8-Debugger-Protokoll übersetzt. Weitere Informationen finden Sie unter https://github.com/node-inspector/node-inspector.