TypeScript + Node.js + Docker: Debugging mit VS Code

Hinweis: Dieser Artikel wurde unter Zuhilfenahme von KI aus dem Englischen übersetzt. Hier geht's zum Originaltext.

TypeScript ist cool, Node.js ist großartig und Docker ist auch ziemlich praktisch. Daher ist es wirklich super, deinen Server mit Node.js in TypeScript zu schreiben und ihn in Docker laufen zu lassen! Nicht so super ist es allerdings, eine gute Debug-Erfahrung mit diesem Setup hinzubekommen.

Während TypeScript und Docker selbst die Entwicklungserfahrung durchaus verbessern können, erfordern sie auch mehr Konfiguration, um alles zum Laufen zu bringen.

Wenn du diese Technologien kombinierst, hast du zwei wesentliche Schichten zwischen deinem Quellcode und dem Code, der ausgeführt wird: Den Kompilierungsschritt und den unterschiedlichen Dateipfad innerhalb deines Docker-Containers.

Der unvermeidliche console.log ist immer eine Option, richtig?

Es ist zwar eine Option, die ohne Konfiguration funktioniert und sicherlich einige Einblicke bieten kann, aber ein Setup, bei dem du Breakpoints setzen und durch deinen Code navigieren und ihn inspizieren kannst, ist irgendwann notwendig. Also keine **console.log**s, zumindest nicht für alles. Aber wie bekommst du funktionierende Breakpoints mit all diesen Abstraktionen hin?

Ich zeige dir ein Setup, das wir aktuell in einem Projekt verwenden, und erkläre die wichtigsten Punkte, die zu einer funktionierenden Konfiguration führen. Der Editor, den wir zum Debuggen des Codes konfigurieren werden, ist VS Code. Neben VS Code, TypeScript, Node.js und Docker werden wir Gulp und Nodemon nutzen, um einen schönen Arbeitsablauf und eine gute Debug-Erfahrung zu erreichen.

Der Workflow auf hoher Ebene sieht so aus:

• Du schreibst TypeScript-Code
• Gulp erkennt Dateiänderungen und löst eine TypeScript-Kompilierung aus
• Der kompilierte JavaScript-Code wird dem Docker-Container über ein gemountetes Volume zur Verfügung gestellt
• Ein Nodemon-Prozess im Container erkennt Dateiänderungen und startet den Node.js-Server im Container neu. Außerdem wird ein Debug-Port freigegeben.

Die Ordnerstruktur, auf der alle folgenden Beispielkonfigurationen basieren, sieht so aus:

Beschriftung: docker-compose.yml

Beschriftung: Dockerfile

Beschriftung: gulpfile.js

Beschriftung: tsconfig.json

In deiner package.json solltest du ein debug-Skript hinzufügen:

Hinweis: Du musst --legacy-watch verwenden, um Dateiänderungen innerhalb eines Docker-Containers zu erkennen.

Zusätzlich brauchen wir eine VS Code Launch-Konfiguration. Glücklicherweise gibt es bereits eine Standard-Konfiguration für docker-node, auf der wir aufbauen können:

Beschriftung: launch.json

Mit docker-compose up sollte dein Server starten. Das konfigurierte Setup sollte dir einen schönen Workflow bieten, der deinen Server automatisch kompiliert und neu startet, wenn du den Quellcode änderst. Aber wenn du jetzt einige Breakpoints in VS Code setzt, werden deine Breakpoints so aussehen:

Beschriftung: Warum bemerkt mich Senpai nicht ☹️ — dein Breakpoint

Was ist also nötig, um das zu beheben? Es gibt zwei Hauptbereiche, die wir anpassen müssen, um unsere Breakpoints in VS Code zum Laufen zu bringen.

• Die Debug-Launch-Konfiguration in VS Code
• Eine möglicherweise notwendige Source-Map-Umschreibung, abhängig von den Quell-, Dist- und Container-Workspace-Ordnerstandorten

Beschriftung: Die launch.json Konfigurationsdatei.

Hinweis: Das ${workspaceFolder} ist der Projektordner, der mit VS Code geöffnet wurde. Die localRoot\, ***remoteRoot\*** und ***outFiles\*** Pfade müssen angepasst werden, um deine Projektstruktur und Container-Einstellungen abzubilden.

In unserem Beispiel müssen wir auch die Source Maps umschreiben, da die TypeScript-Dateien nicht neben den kompilierten Output-Dateien liegen. Um sie auf die ursprüngliche Quelle zurückzuführen, müssen wir den Pfad anpassen und zwei Ordner nach oben gehen.

Beschriftung: Änderungen in gulpfile.js

Das Setzen von "trace": "verbose" in deiner launch.json kann helfen, Probleme mit dem Debugger zu lösen. Dies protokolliert allerlei Konfigurationsdaten in der Debug-Konsole und kann dir helfen, falsch gesetzte Pfade zu finden. Die traurige Sache ist jedoch: Es gibt dir alle konfigurierten Pfade nur dann, wenn alles korrekt funktioniert.

In einer funktionierenden Version würde die Ausgabe z.B. so aussehen:

• Der Remote-Pfad im Container ist korrekt und verweist auf einen gültigen Pfad im dist-Ordner auf meiner lokalen Maschine.
• Der Pfad vom dist-Ordner auf meiner Maschine wird auf die korrekten TypeScript-Dateien gemappt.

Wenn alle Pfade passen, kannst du einfach Breakpoints in deinem TypeScript-Code setzen und VS Code wird sie auslösen: Großartig! 🎉 🎉 🎉

Aber wenn sie nicht richtig eingerichtet sind, erhältst du nur eine Ausgabe wie diese:

Das ist eine Menge Output 😩...

Ich habe die wichtigen Teile für dich hervorgehoben:

• setBreakpoints({"source": {"name": "File.ts", "path": "/projects/ts-node-in-docker/app/server/src/File.ts"
• "message": "Breakpoint ignored because generated code not found (source map problem?)."

Dies würde uns zum Beispiel zeigen, dass die Source-Map-Pfade im kompilierten Code falsch sind — genau das haben wir bereits mit der Gulp Source-Map-Umschreibung behoben.

Nur wenn die Source-Map-Zuordnungen zwischen den lokalen kompilierten Dateien und deinen Quelldateien übereinstimmen, wird der Debugger versuchen, die kompilierten lokalen Dateien auf die im Docker-Container laufenden abzubilden.

Behebe also zuerst das Source-Map-Setup auf deiner lokalen Maschine. Wenn es korrekt ist und du Breakpoints setzen kannst, kannst du die Einstellungen anpassen, um die kompilierten Dateien auf die im Container abzubilden.

• Verwende "trace": "verbose", um Probleme mit deinen Breakpoints und deiner launch.json zu verstehen
• In deiner launch.json:
  • "cwd" = dein VS Code-Projektverzeichnis
  • "localRoot" = wo deine TypeScript-Quelldateien liegen
  • "remoteRoot" = Workspace-Ordner, wie in deiner Dockerfile konfiguriert
  • "outFiles" = Glob-Muster, wohin die kompilierten JavaScript-Dateien auf deiner lokalen Maschine geschrieben werden
• Falls nötig, schreibe Quellpfade um, damit VS Code die Quelldateien für die kompilierten finden kann
• Öffne Port 9222 in Docker
• Starte den Node-Server mit --inspect=0.0.0.0:9222