ist jetzt verfügbar! Lesen Sie über die neuen Funktionen und Fehlerbehebungen vom November.

Node.js Debugging in VS Code

Der Visual Studio Code-Editor verfügt über integrierte Debugging-Unterstützung für die Node.js-Laufzeit und kann JavaScript, TypeScript und viele andere Sprachen debuggen, die in JavaScript transpilert werden. Das Einrichten eines Projekts für Node.js-Debugging ist mit VS Code unkompliziert, da VS Code geeignete Standardeinstellungen für die Startkonfiguration und Snippets bereitstellt.

Es gibt mehrere Möglichkeiten, Ihre Node.js-Programme in VS Code zu debuggen

Auto Attach

Wenn die Funktion **Auto Attach** aktiviert ist, hängt sich der Node-Debugger automatisch an bestimmte Node.js-Prozesse an, die aus dem integrierten Terminal von VS Code gestartet wurden. Um die Funktion zu aktivieren, verwenden Sie entweder den Befehl **Toggle Auto Attach** aus der Befehlspalette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) oder, wenn sie bereits aktiviert ist, verwenden Sie das Statusleistenelement **Auto Attach**.

Es gibt drei Modi für Auto Attach, die Sie in der Ergebnis-Quick-Pick und über die Einstellung **debug.javascript.autoAttachFilter** auswählen können

  • smart - Wenn Sie ein Skript außerhalb Ihres node_modules-Ordners ausführen oder ein gängiges "Runner"-Skript wie mocha oder ts-node verwenden, wird der Prozess debuggt. Sie können die Zulassungsliste für "Runner"-Skripte über die Einstellung **Auto Attach Smart Pattern** (debug.javascript.autoAttachSmartPattern) konfigurieren.
  • always - Alle im integrierten Terminal gestarteten Node.js-Prozesse werden debuggt.
  • onlyWithFlag - Nur Prozesse, die mit der Option --inspect oder --inspect-brk gestartet wurden, werden debuggt.

Nachdem Sie **Auto Attach** aktiviert haben, müssen Sie Ihr Terminal neu starten, indem Sie auf das ⚠-Symbol oben rechts im Terminal klicken oder einfach ein neues erstellen. Dann sollte sich der Debugger innerhalb einer Sekunde an Ihr Programm anhängen

Auto Attach

Wenn Auto Attach aktiviert ist, erscheint der Eintrag `Auto Attach` in der Statusleiste am unteren Rand des VS Code-Fensters. Ein Klick darauf ermöglicht es Ihnen, den Auto Attach-Modus zu ändern oder ihn vorübergehend zu deaktivieren. Das vorübergehende Deaktivieren von Auto Attach ist nützlich, wenn Sie einige einmalige Programme ausführen, bei denen Sie kein Debugging benötigen, die Funktion aber nicht vollständig deaktivieren möchten.

Zusätzliche Konfiguration

Weitere Eigenschaften der Startkonfiguration

Sie können andere Eigenschaften, die normalerweise in launch.json zu finden sind, auf Auto Attach in der Einstellung **debug.javascript.terminalOptions** anwenden. Um beispielsweise Node-Interna zu Ihren skipFiles hinzuzufügen, könnten Sie Folgendes zu Ihren Benutzer- oder Arbeitsbereichseinstellungen hinzufügen

  "debug.javascript.terminalOptions": {
    "skipFiles": [
      "<node_internals>/**"
    ]
  },

Auto Attach Smart Patterns

Im smart-Auto-Attach-Modus versucht VS Code, sich an Ihren Code anzuhängen und nicht an Build-Tools, an denen Sie kein Interesse haben, anzuhängen. Dies geschieht durch den Abgleich des Hauptskripts mit einer Liste von Glob-Mustern. Die Glob-Muster sind in der Einstellung **debug.javascript.autoAttachSmartPattern** konfigurierbar, die standardmäßig auf Folgendes eingestellt ist

[
  '!**/node_modules/**', // exclude scripts in node_modules folders
  '**/$KNOWN_TOOLS$/**' // but include some common tools
];

$KNOWN_TOOLS$ wird durch eine Liste gängiger "Code-Runner" ersetzt, wie z. B. ts-node, mocha, ava und so weiter. Sie können diese Liste ändern, wenn diese Einstellungen nicht funktionieren. Um beispielsweise mocha auszuschließen und my-cool-test-runner einzuschließen, könnten Sie zwei Zeilen hinzufügen

[
  '!**/node_modules/**',
  '**/$KNOWN_TOOLS$/**',
  '!**/node_modules/mocha/**', // use "!" to exclude all scripts in "mocha" node modules
  '**/node_modules/my-cool-test-runner/**' // include scripts in the custom test runner
];

JavaScript Debug Terminal

Ähnlich wie bei Auto Attach debuggt das JavaScript Debug Terminal automatisch jeden Node.js-Prozess, den Sie darin ausführen. Sie können ein Debug Terminal erstellen, indem Sie den Befehl **Debug: Create JavaScript Debug Terminal** aus der Befehlspalette (kbs(workbench.action.showCommands)) ausführen oder indem Sie **Create JavaScript Debug Terminal** aus dem Dropdown-Menü des Terminal-Umschalters auswählen.

Create Debug Terminal

Zusätzliche Konfiguration

Weitere Eigenschaften der Startkonfiguration

Sie können andere Eigenschaften, die normalerweise in launch.json zu finden sind, auf das Debug Terminal in der Einstellung **debug.javascript.terminalOptions** anwenden. Um beispielsweise Node-Interna zu Ihren skipFiles hinzuzufügen, könnten Sie Folgendes zu Ihren Benutzer- oder Arbeitsbereichseinstellungen hinzufügen

"debug.javascript.terminalOptions": {
  "skipFiles": [
    "<node_internals>/**"
  ]
},

Launch Configuration

Startkonfigurationen sind die traditionelle Methode zur Einrichtung des Debuggings in VS Code und bieten die meisten Konfigurationsoptionen für die Ausführung komplexer Anwendungen.

In diesem Abschnitt gehen wir detaillierter auf Konfigurationen und Funktionen für fortgeschrittene Debugging-Szenarien ein. Sie finden Anweisungen zum Debuggen mit Source Maps, Überspringen von externem Code, Remote-Debugging und vielem mehr.

Wenn Sie ein Einführungsvideo sehen möchten, siehe Erste Schritte mit dem Debugging in VS Code.

Hinweis: Wenn Sie gerade erst mit VS Code beginnen, können Sie sich über allgemeine Debugging-Funktionen und die Erstellung von launch.json-Konfigurationsdateien im Thema Debugging informieren.

Launch-Konfigurationsattribute

Debugging-Konfigurationen werden in einer Datei launch.json im Ordner .vscode Ihres Arbeitsbereichs gespeichert. Eine Einführung in die Erstellung und Verwendung von Debugging-Konfigurationsdateien finden Sie im allgemeinen Artikel Debugging.

Im Folgenden finden Sie eine Referenz der gängigen launch.json-Attribute, die spezifisch für den Node.js-Debugger sind. Sie können die vollständige Liste der Optionen in der Dokumentation zu den vscode-js-debug-Optionen einsehen.

Die folgenden Attribute werden in Startkonfigurationen vom Typ launch und attach unterstützt

  • outFiles - Array von Glob-Mustern zum Auffinden von generierten JavaScript-Dateien. Siehe Abschnitt Source Maps.
  • resolveSourceMapLocations - Ein Array von Glob-Mustern für Speicherorte, an denen Source Maps geparst werden sollen. Siehe Abschnitt Source Maps.
  • timeout - Beim Neustart einer Sitzung geben Sie nach dieser Anzahl von Millisekunden auf. Siehe Abschnitt An Node.js anhängen.
  • stopOnEntry - Unterbrechen Sie sofort, wenn das Programm gestartet wird.
  • localRoot - Stammverzeichnis von VS Code. Siehe Abschnitt Remote-Debugging unten.
  • remoteRoot - Stammverzeichnis von Node. Siehe Abschnitt Remote-Debugging unten.
  • smartStep - Versuchen Sie, automatisch über Code zu springen, der nicht zu Quelldateien zugeordnet wird. Siehe Abschnitt Smart Stepping.
  • skipFiles - Überspringen Sie automatisch Dateien, die von diesen Glob-Mustern abgedeckt sind. Siehe Abschnitt Uninteressanten Code überspringen.
  • trace - Aktivieren Sie die Diagnoseausgabe.

Diese Attribute sind nur für Startkonfigurationen vom Anfragetyp launch verfügbar

  • program - Ein absoluter Pfad zum zu debuggenden Node.js-Programm.
  • args - An das zu debuggende Programm übergebene Argumente. Dieses Attribut ist vom Typ Array und erwartet einzelne Argumente als Array-Elemente.
  • cwd - Starten Sie das zu debuggende Programm in diesem Verzeichnis.
  • runtimeExecutable - Absoluter Pfad zur zu verwendenden Laufzeitausführung. Standard ist node. Siehe Abschnitt Startkonfigurationsunterstützung für 'npm' und andere Tools.
  • runtimeArgs - Optionale Argumente, die an die Laufzeitausführung übergeben werden.
  • runtimeVersion - Wenn "nvm" (oder "nvm-windows") oder "nvs" zur Verwaltung von Node.js-Versionen verwendet wird, kann dieses Attribut verwendet werden, um eine bestimmte Version von Node.js auszuwählen. Siehe Abschnitt Multi-Version-Unterstützung unten.
  • env - Optionale Umgebungsvariablen. Dieses Attribut erwartet Umgebungsvariablen als Liste von Zeichenfolgen-Typ-Schlüssel/Wert-Paaren.
  • envFile - Optionaler Pfad zu einer Datei, die Umgebungsvariablen-Definitionen enthält. Siehe Abschnitt Umgebungsvariablen aus externer Datei laden unten.
  • console - Die Konsole zum Starten des Programms (internalConsole, integratedTerminal, externalTerminal). Siehe Abschnitt Node Console unten.
  • outputCapture - Wenn auf std gesetzt, werden Ausgaben von stdout/stderr des Prozesses in der Debug-Konsole angezeigt, anstatt über den Debug-Port auf Ausgaben zu hören. Dies ist nützlich für Programme oder Protokollbibliotheken, die direkt in die stdout/stderr-Streams schreiben, anstatt die console.*-APIs zu verwenden.

Dieses Attribut ist nur für Startkonfigurationen vom Anfragetyp attach verfügbar

  • restart - Starten Sie die Verbindung nach Beendigung neu. Siehe Abschnitt Debug-Sitzungen bei Quellcodeänderungen automatisch neu starten.
  • port - Zu verwendender Debug-Port. Siehe Abschnitte An Node.js anhängen und Remote-Debugging.
  • address - TCP/IP-Adresse des Debug-Ports. Siehe Abschnitte An Node.js anhängen und Remote-Debugging.
  • processId - Der Debugger versucht, sich nach dem Senden eines USR1-Signals an diesen Prozess anzuhängen. Mit dieser Einstellung kann sich der Debugger an einen bereits laufenden Prozess anhängen, der nicht im Debug-Modus gestartet wurde. Bei Verwendung des Attributs processId wird der Debug-Port automatisch basierend auf der Node.js-Version (und dem verwendeten Protokoll) ermittelt und kann nicht explizit konfiguriert werden. Geben Sie daher kein Attribut port an.
  • continueOnAttach - Ob der Prozess fortgesetzt werden soll, wenn er beim Anhängen angehalten wird. Diese Option ist nützlich, wenn Sie Ihr Programm mit --inspect-brk starten.

Startkonfigurationen für gängige Szenarien

Sie können IntelliSense (⌃Space (Windows, Linux Ctrl+Space)) in Ihrer Datei launch.json aufrufen, um Startkonfigurations-Snippets für gängige Node.js-Debugging-Szenarien anzuzeigen.

Launch configuration snippets for Node.js

Sie können die Snippets auch über die Schaltfläche **Add Configuration...** unten rechts im Editorfenster von launch.json aufrufen.

Add Configuration button

Die folgenden Snippets sind verfügbar

  • Programm starten: Ein Node.js-Programm im Debug-Modus starten.
  • Via npm starten: Ein Node.js-Programm über ein npm 'debug'-Skript starten. Sie können ein npm-Debug-Skript aus Ihrer Startkonfiguration verwenden, wenn es in Ihrer package.json definiert wurde. Der in Ihrem npm-Skript verwendete Debug-Port muss dem im Snippet angegebenen Port entsprechen.
  • Anhängen: An den Debug-Port eines lokal laufenden Node.js-Programms anhängen. Stellen Sie sicher, dass das zu debuggende Node.js-Programm im Debug-Modus gestartet wurde und der verwendete Debug-Port derselbe ist wie der im Snippet angegebene.
  • An Remote-Programm anhängen: An den Debug-Port eines Node.js-Programms anhängen, das auf dem von address angegebenen Host läuft. Stellen Sie sicher, dass das zu debuggende Node.js-Programm im Debug-Modus gestartet wurde und der verwendete Debug-Port derselbe ist wie der im Snippet angegebene. Um VS Code beim Zuordnen von Quelldateien zwischen Ihrem Arbeitsbereich und dem Dateisystem des Remote-Hosts zu helfen, stellen Sie sicher, dass Sie korrekte Pfade für die Attribute localRootund remoteRoot angeben.
  • Anhängen nach Prozess-ID: Öffnen Sie den Prozess-Selektor, um einen Node- oder Gulp-Prozess zum Debuggen auszuwählen. Mit dieser Startkonfiguration können Sie sich sogar an einen Node- oder Gulp-Prozess anhängen, der nicht im Debug-Modus gestartet wurde.
  • Nodemon-Einrichtung: Verwenden Sie nodemon, um eine Debug-Sitzung automatisch neu zu starten, wenn sich der JavaScript-Quellcode geändert hat. Stellen Sie sicher, dass nodemon global installiert ist. Beachten Sie, dass das Beenden der Debug-Sitzung nur das zu debuggende Programm beendet, nicht nodemon selbst. Um nodemon zu beenden, drücken Sie Strg+C im integrierten Terminal.
  • Mocha-Tests: Debuggen Sie Mocha-Tests in einem test-Ordner Ihres Projekts. Stellen Sie sicher, dass Ihr Projekt 'mocha' in seinem node_modules-Ordner installiert hat.
  • Yeoman-Generator: Debuggen Sie einen Yeoman-Generator. Das Snippet fragt Sie nach dem Namen des Generators. Stellen Sie sicher, dass Ihr Projekt 'yo' in seinem node_modules-Ordner installiert hat und dass Ihr generiertes Projekt für das Debugging installiert wurde, indem Sie npm link im Projektordner ausführen.
  • Gulp-Aufgabe: Debuggen Sie eine Gulp-Aufgabe. Stellen Sie sicher, dass Ihr Projekt 'gulp' in seinem node_modules-Ordner installiert hat.
  • Electron Main: Debuggen Sie den Haupt-Node.js-Prozess einer Electron-Anwendung. Das Snippet geht davon aus, dass die Electron-Ausführungsdatei im Verzeichnis node_modules/.bin des Arbeitsbereichs installiert wurde.

Node-Konsole

Standardmäßig werden Node.js-Debug-Sitzungen im internen VS Code Debug Console gestartet. Da die Debug-Konsole keine Programme unterstützt, die Eingaben von der Konsole lesen müssen, können Sie entweder ein externes Terminal aktivieren oder das VS Code Integrated Terminal verwenden, indem Sie das Attribut console in Ihrer Startkonfiguration auf externalTerminal oder integratedTerminal setzen. Der Standard ist internalConsole.

In einem externen Terminal können Sie das zu verwendende Terminalprogramm über die Einstellungen terminal.external.windowsExec, terminal.external.osxExec und terminal.external.linuxExec konfigurieren.

Startkonfigurationsunterstützung für 'npm' und andere Tools

Anstatt das Node.js-Programm direkt mit node zu starten, können Sie 'npm'-Skripte oder andere Task-Runner-Tools direkt aus einer Startkonfiguration verwenden

  • Sie können jedes Programm, das im PATH verfügbar ist (z. B. 'npm', 'mocha', 'gulp' usw.), für das Attribut runtimeExecutable verwenden, und Argumente können über runtimeArgs übergeben werden.
  • Sie müssen das Attribut program nicht festlegen, wenn Ihr npm-Skript oder ein anderes Tool implizit das zu startende Programm angibt.

Schauen wir uns ein 'npm'-Beispiel an. Wenn Ihre package.json ein 'debug'-Skript hat, zum Beispiel

  "scripts": {
    "debug": "node myProgram.js"
  },

würde die entsprechende Startkonfiguration so aussehen

{
  "name": "Launch via npm",
  "type": "node",
  "request": "launch",
  "cwd": "${workspaceFolder}",
  "runtimeExecutable": "npm",
  "runtimeArgs": ["run-script", "debug"]
}

Multi-Version-Unterstützung

Wenn Sie 'nvm' (oder 'nvm-windows') zur Verwaltung Ihrer Node.js-Versionen verwenden, können Sie ein Attribut runtimeVersion in einer Startkonfiguration angeben, um eine bestimmte Version von Node.js auszuwählen

{
  "type": "node",
  "request": "launch",
  "name": "Launch test",
  "runtimeVersion": "14",
  "program": "${workspaceFolder}/test.js"
}

Wenn Sie 'nvs' zur Verwaltung Ihrer Node.js-Versionen verwenden, können Sie das Attribut runtimeVersion verwenden, um eine bestimmte Version, Architektur und ein bestimmtes Flavor von Node.js auszuwählen, zum Beispiel

{
  "type": "node",
  "request": "launch",
  "name": "Launch test",
  "runtimeVersion": "chackracore/8.9.4/x64",
  "program": "${workspaceFolder}/test.js"
}

Stellen Sie sicher, dass die Node.js-Versionen installiert sind, die Sie mit dem Attribut runtimeVersion verwenden möchten, da die Funktion die Version nicht automatisch herunterlädt und installiert. Sie müssen beispielsweise etwas wie nvm install 7.10.1 oder nvs add 7.10.1 aus dem integrierten Terminal ausführen, wenn Sie "runtimeVersion": "7.10.1" zu Ihrer Startkonfiguration hinzufügen möchten.

Wenn Sie die Neben- und Patch-Version weglassen und beispielsweise "runtimeVersion": "14" haben, wird die neueste unter Ihrem System installierte Version 14.x.y verwendet.

Umgebungsvariablen aus externer Datei laden

Der VS Code Node-Debugger unterstützt das Laden von Umgebungsvariablen aus einer Datei und deren Übergabe an die Node.js-Laufzeit. Um diese Funktion zu nutzen, fügen Sie Ihrer Startkonfiguration ein Attribut envFile hinzu und geben Sie den absoluten Pfad zu der Datei an, die die Umgebungsvariablen enthält

   //...
   "envFile": "${workspaceFolder}/.env",
   "env": { "USER": "john doe" }
   //...

Jede Umgebungsvariable, die im env-Dictionary angegeben ist, überschreibt Variablen, die aus der Datei geladen wurden.

Hier ist ein Beispiel für eine .env-Datei

USER=doe
PASSWORD=abc123

# a comment

# an empty value:
empty=

# new lines expanded in quoted strings:
lines="foo\nbar"

An Node.js anhängen

Wenn Sie den VS Code-Debugger an ein externes Node.js-Programm anhängen möchten, starten Sie Node.js wie folgt

node --inspect program.js

oder wenn das Programm nicht starten, sondern auf das Anhängen des Debuggers warten soll

node --inspect-brk program.js

Optionen zum Anhängen des Debuggers an Ihr Programm

  • Öffnen Sie einen "Prozess-Selektor", der alle potenziellen Kandidatenprozesse auflistet und Sie einen auswählen lässt, oder
  • Erstellen Sie eine "Attach"-Konfiguration, die alle Konfigurationsoptionen explizit angibt, und drücken Sie dann **F5**.

Lassen Sie uns diese Optionen im Detail durchgehen

Aktion "An Node-Prozess anhängen"

Der Befehl **Attach to Node Process** aus der Befehlspalette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) öffnet ein Quick Pick-Menü, das alle potenziellen Prozesse auflistet, die für den Node.js-Debugger verfügbar sind

Node.js Process picker

Die einzelnen Prozesse, die im Selektor aufgelistet sind, zeigen den Debug-Port und die Prozess-ID an. Sobald Sie Ihren Node.js-Prozess in dieser Liste auswählen, versucht der Node.js-Debugger, sich daran anzuhängen.

Neben Node.js-Prozessen zeigt der Selektor auch andere Programme an, die mit einer der verschiedenen Formen von --inspect-Argumenten gestartet wurden. Dies ermöglicht das Anhängen an Hilfsprozesse von Electron oder VS Code.

Einrichten einer "Attach"-Konfiguration

Diese Option erfordert mehr Aufwand, aber im Gegensatz zu den beiden vorherigen Optionen können Sie verschiedene Debug-Konfigurationsoptionen explizit konfigurieren.

Die einfachste "Attach"-Konfiguration sieht so aus

{
  "name": "Attach to Process",
  "type": "node",
  "request": "attach",
  "port": 9229
}

Der Port 9229 ist der Standard-Debug-Port der Optionen --inspect und --inspect-brk. Um einen anderen Port zu verwenden (z. B. 12345), fügen Sie ihn den Optionen hinzu: --inspect=12345 und --inspect-brk=12345 und ändern Sie das Attribut port in der Startkonfiguration entsprechend.

Um sich an einen Node.js-Prozess anzuhängen, der nicht im Debug-Modus gestartet wurde, können Sie dies tun, indem Sie die Prozess-ID des Node.js-Prozesses als Zeichenfolge angeben

{
  "name": "Attach to Process",
  "type": "node",
  "request": "attach",
  "processId": "53426"
}

Um zu vermeiden, dass wiederholt eine neue Prozess-ID in der Startkonfiguration eingegeben werden muss, unterstützt der Node-Debugger eine Befehlsvariable PickProcess, die den Prozess-Selektor (von oben) öffnet.

Unter Verwendung der Variable PickProcess sieht die Startkonfiguration so aus

{
  "name": "Attach to Process",
  "type": "node",
  "request": "attach",
  "processId": "${command:PickProcess}"
}

Debug-Sitzung beenden

Die Aktion **Debug: Stop** (verfügbar in der Debug-Werkzeugleiste oder über die **Befehlspalette**) beendet die Debug-Sitzung.

Wenn die Debug-Sitzung im "Attach"-Modus gestartet wurde (und die rote Beenden-Schaltfläche in der Debug-Werkzeugleiste ein überlagertes "Stecker"-Symbol anzeigt), trennt das Drücken von **Stop** den Node.js-Debugger vom Debuggee, der dann die Ausführung fortsetzt.

Wenn sich die Debug-Sitzung im "Launch"-Modus befindet, bewirkt das Drücken von **Stop** Folgendes

  1. Beim ersten Drücken von **Stop** wird der Debuggee aufgefordert, sich ordnungsgemäß herunterzufahren, indem ein SIGINT-Signal gesendet wird. Der Debuggee kann dieses Signal abfangen, Bereinigungen nach Bedarf durchführen und sich dann herunterfahren. Wenn keine Breakpoints (oder Probleme) im Shutdown-Code vorhanden sind, werden der Debuggee und die Debug-Sitzung beendet.

  2. Wenn der Debugger jedoch einen Breakpoint im Shutdown-Code trifft oder der Debuggee sich nicht ordnungsgemäß selbst beendet, wird die Debug-Sitzung nicht beendet. In diesem Fall erzwingt das erneute Drücken von **Stop** das Beenden des Debuggees und seiner Kindprozesse (SIGKILL).

Wenn Sie feststellen, dass eine Debug-Sitzung nicht endet, wenn Sie auf die rote Schaltfläche **Stop** klicken, drücken Sie die Schaltfläche erneut, um das Beenden des Debuggees zu erzwingen.

Unter Windows beendet das Drücken von **Stop** den Debuggee und seine Kindprozesse zwangsweise.

Source Maps

Der JavaScript-Debugger von VS Code unterstützt Source Maps, die beim Debuggen von transpilerten Sprachen wie TypeScript oder minifiziertem/verschleiertem JavaScript helfen. Mit Source Maps ist es möglich, durch den Original-Quellcode zu steppen oder Breakpoints im Original-Quellcode zu setzen. Wenn keine Source Map für den Original-Quellcode existiert oder wenn die Source Map fehlerhaft ist und nicht erfolgreich zwischen dem Quellcode und dem generierten JavaScript zugeordnet werden kann, dann werden Breakpoints als nicht verifiziert angezeigt (graue hohle Kreise).

Das Attribut sourceMaps, das standardmäßig auf true gesetzt ist, steuert die Source-Map-Funktion. Der Debugger versucht immer, Source Maps zu verwenden (wenn er welche finden kann), und infolgedessen können Sie sogar eine Quelldatei (z. B. app.ts) mit dem Attribut program angeben. Wenn Sie Source Maps aus irgendeinem Grund deaktivieren müssen, können Sie das Attribut sourceMaps auf false setzen.

Tool-Konfiguration

Da Source Maps nicht immer automatisch erstellt werden, sollten Sie sicherstellen, dass Sie Ihren Transpiler so konfigurieren, dass sie erstellt werden. Zum Beispiel

TypeScript

Für TypeScript können Sie Sourcemaps aktivieren, indem Sie --sourceMap an tsc übergeben oder "sourceMap": true in Ihrer tsconfig.json-Datei hinzufügen.

tsc --sourceMap --outDir bin app.ts

Babel

Für Babel sollten Sie die Option sourceMaps auf true setzen oder die Option --source-maps übergeben, wenn Sie Ihren Code kompilieren.

npx babel script.js --out-file script-compiled.js --source-maps

Webpack

Webpack hat zahlreiche Source-Map-Optionen. Wir empfehlen, die Eigenschaft devtool: "source-map" in Ihrer webpack.config.js für die beste Ergebnisgenauigkeit festzulegen, obwohl Sie mit anderen Einstellungen experimentieren können, die zu Verlangsamungen Ihres Builds führen.

Außerdem, wenn Sie zusätzliche Kompilierungsschritte in webpack haben, wie z. B. die Verwendung eines TypeScript-Loaders, sollten Sie auch sicherstellen, dass diese Schritte so konfiguriert sind, dass sie Sourcemaps generieren. Andernfalls werden die von webpack generierten Sourcemaps auf den kompilierten Code des Loaders und nicht auf die tatsächlichen Quellen zurückverweisen.

Source Map Erkennung

Standardmäßig durchsucht VS Code Ihren gesamten Arbeitsbereich, ausgenommen node_modules, nach Sourcemaps. In großen Arbeitsbereichen kann diese Suche langsam sein. Sie können die Speicherorte konfigurieren, an denen VS Code nach Source Maps sucht, indem Sie das Attribut outFiles in Ihrer launch.json festlegen. Diese Konfiguration würde beispielsweise nur Sourcemaps für .js-Dateien im bin-Ordner finden

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch TypeScript",
      "type": "node",
      "request": "launch",
      "program": "app.ts",
      "outFiles": ["${workspaceFolder}/bin/**/*.js"]
    }
  ]
}

Beachten Sie, dass outFiles mit Ihren JavaScript-Dateien übereinstimmen sollte, nicht mit den Source-Map-Dateien (die möglicherweise auf .map statt auf .js enden).

Source Map Auflösung

Standardmäßig werden nur Source Maps in Ihren outFiles aufgelöst. Dieses Verhalten wird verwendet, um zu verhindern, dass Abhängigkeiten mit Ihren gesetzten Breakpoints interferieren. Wenn Sie beispielsweise eine Datei src/index.ts hatten und eine Abhängigkeit eine Source Map mit dem Verweis webpack:///./src/index.ts hatte, würde dies fälschlicherweise auf Ihre Quelldatei verweisen und zu unerwarteten Ergebnissen führen.

Sie können dieses Verhalten konfigurieren, indem Sie die Option resolveSourceMapLocations festlegen. Wenn diese auf null gesetzt ist, wird jede Source Map aufgelöst. Diese Konfiguration würde beispielsweise zusätzlich die Auflösung von Source Maps in node_modules/some-dependency erlauben

  "resolveSourceMapLocations": [
    "out/**/*.js",
    "node_modules/some-dependency/**/*.js",
  ]

Smart Stepping

Wenn das Attribut smartStep in einer Startkonfiguration auf true gesetzt ist, überspringt VS Code beim Durchlaufen von Code im Debugger automatisch "uninteressanten Code". "Uninteressanter Code" ist Code, der von einem Transpilierungsprozess generiert wurde, aber nicht von einer Source Map abgedeckt ist, sodass er nicht auf den ursprünglichen Quellcode zurückverweist. Dieser Code stört Sie beim Durchlaufen von Quellcode im Debugger, da er den Debugger zwischen dem ursprünglichen Quellcode und generiertem Code wechseln lässt, an dem Sie nicht interessiert sind. smartStep springt automatisch über Code, der nicht von einer Source Map abgedeckt ist, bis es eine Stelle erreicht, die wieder von einer Source Map abgedeckt ist.

Smart Stepping ist besonders nützlich für Fälle wie die Down-Kompilierung von async/await in TypeScript, bei denen der Compiler Hilfscode einfügt, der nicht von einer Source Map abgedeckt ist.

Die Funktion smartStep gilt nur für JavaScript-Code, der aus Quellcode generiert wurde und daher eine Source Map hat. Für JavaScript ohne Quellen hat die Option für Smart Stepping keine Auswirkung.

Tipps zu JavaScript Source Maps

Ein häufiges Problem beim Debuggen mit Source Maps ist, dass Sie einen Breakpoint setzen, und er wird grau. Wenn Sie den Mauszeiger darüber bewegen, sehen Sie die Meldung: "Breakpoint ignored because generated code not found (source map problem?)". Was nun? Es gibt eine Reihe von Problemen, die dazu führen können. Zuerst eine kurze Erklärung, wie der Node-Debug-Adapter Source Maps handhabt.

Wenn Sie einen Breakpoint in app.ts setzen, muss der Debug-Adapter den Pfad zu app.js ermitteln, der transpilierte Version Ihrer TypeScript-Datei, die tatsächlich in Node ausgeführt wird. Es gibt jedoch keinen einfachen Weg, dies vom .ts-Datei aus zu ermitteln. Stattdessen verwendet der Debug-Adapter das Attribut outFiles in der launch.json, um alle transpilierten .js-Dateien zu finden und diese nach einer Source Map zu parsen, die die Speicherorte ihrer zugehörigen .ts-Dateien enthält.

Wenn Sie Ihre app.ts-Datei mit aktivierten Source Maps in TypeScript kompilieren, erzeugt sie entweder eine app.js.map-Datei oder eine Source Map, die als Base64-kodierte Zeichenfolge in einem Kommentar am Ende der app.js-Datei eingebettet ist. Um die mit dieser Map verknüpften .ts-Dateien zu finden, sucht der Debug-Adapter nach zwei Eigenschaften in der Source Map: sources und sourceRoot. sourceRoot ist optional – wenn vorhanden, wird sie jedem Pfad in sources, einem Array von Pfaden, vorangestellt. Das Ergebnis ist ein Array von absoluten oder relativen Pfaden zu .ts-Dateien. Relative Pfade werden relativ zur Source Map aufgelöst.

Schließlich sucht der Debug-Adapter nach dem vollständigen Pfad von app.ts in dieser resultierenden Liste von .ts-Dateien. Wenn es eine Übereinstimmung gibt, hat er die Source-Map-Datei gefunden, die er zum Zuordnen von app.ts zu app.js verwenden kann. Wenn es keine Übereinstimmung gibt, kann er den Breakpoint nicht binden, und er wird grau.

Hier sind einige Dinge, die Sie ausprobieren können, wenn Ihre Breakpoints grau werden

  • Führen Sie während des Debuggens den Befehl Debug: Diagnose Breakpoint Problems aus. Dieser Befehl öffnet ein Tool, das Hinweise zur Behebung von Problemen aus der Befehlspalette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) liefert.
  • Haben Sie mit aktivierten Source Maps kompiliert? Stellen Sie sicher, dass es .js.map-Dateien gibt oder dass Source Maps in Ihren .js-Dateien eingebettet sind.
  • Sind die Eigenschaften sourceRoot und sources in Ihrer Source Map korrekt? Können sie kombiniert werden, um den korrekten Pfad zur .ts-Datei zu erhalten?
  • Haben Sie den Ordner in VS Code mit falscher Groß-/Kleinschreibung geöffnet? Es ist möglich, den Ordner foo/ über die Befehlszeile wie code FOO zu öffnen, in welchem Fall Source Maps möglicherweise nicht korrekt aufgelöst werden.
  • Versuchen Sie, auf Stack Overflow nach Hilfe für Ihre spezifische Einrichtung zu suchen oder ein Problem auf GitHub zu melden.
  • Versuchen Sie, eine debugger-Anweisung hinzuzufügen. Wenn sie in der .ts-Datei dort unterbrochen wird, aber Breakpoints an dieser Stelle nicht gebunden werden, sind das nützliche Informationen, die Sie in einem GitHub-Issue angeben können.

Überschreiben von Source Map Pfaden

Der Debugger verwendet sourceMapPathOverrides, um benutzerdefinierte Zuordnungen von Sourcemap zu Festplattenpfaden zu implementieren. Für die meisten Tools gibt es gute Standardeinstellungen, aber in fortgeschrittenen Fällen müssen Sie sie möglicherweise anpassen. Die Standardpfadüberschreibungen sind eine Objektzuordnung, die so aussieht

{
  'webpack:///./~/*': "${workspaceFolder}/node_modules/*",
  'webpack:////*': '/*',
  'webpack://@?:*/?:*/*': "${workspaceFolder}/*",
  // and some more patterns...
}

Dies ordnet Pfade oder URLs in der Source Map von links nach rechts zu. Das Muster ?:* ist eine nicht-gierige, nicht-erfassende Übereinstimmung, und * ist eine gierige erfassende Übereinstimmung. Der Debugger ersetzt dann den entsprechenden * im Muster auf der rechten Seite durch das Fragment, das aus dem Source-Map-Pfad erfasst wurde. Zum Beispiel würde das letzte Muster im obigen Beispiel webpack://@my/package/foo/bar auf ${workspaceFolder}/foo/bar abbilden.

Beachten Sie, dass für das Debugging von Browsern webRoot anstelle von workspaceFolder in den Standard-sourceMapPathOverrides verwendet wird.

Remote-Debugging

Hinweis: VS Code verfügt jetzt über universelle Remote-Entwicklungsfunktionen. Mit den Remote Development-Erweiterungen ist die Node.js-Entwicklung in Remote-Szenarien und Containern nicht anders als die Node.js-Entwicklung in einer lokalen Einrichtung. Dies ist der empfohlene Weg zum Remote-Debuggen von Node.js-Programmen. Informieren Sie sich im Abschnitt Erste Schritte und in den Remote-Tutorials, um mehr zu erfahren.

Wenn Sie keine der Remote-Entwicklungs-Erweiterungen zum Debuggen Ihres Node.js-Programms verwenden können, finden Sie unten eine Anleitung, wie Sie ein Remote-Node.js-Programm von Ihrer lokalen VS Code-Instanz aus debuggen können.

Der Node.js-Debugger unterstützt Remote-Debugging, bei dem Sie sich an einen Prozess anhängen, der auf einem anderen Computer oder in einem Container läuft. Geben Sie einen Remote-Host über das Attribut address an. Zum Beispiel

{
  "type": "node",
  "request": "attach",
  "name": "Attach to remote",
  "address": "192.168.148.2", // <- remote address here
  "port": 9229
}

Standardmäßig streamt VS Code den debuggten Quellcode vom Remote-Node.js-Ordner zum lokalen VS Code und zeigt ihn in einem schreibgeschützten Editor an. Sie können durch diesen Code steppen, aber ihn nicht ändern. Wenn Sie möchten, dass VS Code stattdessen die bearbeitbare Quelle aus Ihrem Arbeitsbereich öffnet, können Sie eine Zuordnung zwischen den Remote- und lokalen Speicherorten einrichten. Die Attribute localRoot und remoteRoot können verwendet werden, um Pfade zwischen einem lokalen VS Code-Projekt und einem (Remote-)Node.js-Ordner zuzuordnen. Dies funktioniert auch lokal auf demselben System oder über verschiedene Betriebssysteme hinweg. Immer wenn ein Code-Pfad vom Remote-Node.js-Ordner in einen lokalen VS Code-Pfad konvertiert werden muss, wird der Pfad remoteRoot vom Pfad gestrippt und durch localRoot ersetzt. Für die umgekehrte Konvertierung wird der Pfad localRoot durch remoteRoot ersetzt.

{
  "type": "node",
  "request": "attach",
  "name": "Attach to remote",
  "address": "TCP/IP address of process to be debugged",
  "port": 9229,
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "C:\\Users\\username\\project\\server"
}

Zugriff auf geladene Skripte

Wenn Sie einen Breakpoint in einem Skript setzen müssen, das nicht Teil Ihres Arbeitsbereichs ist und daher nicht einfach durch normale VS Code-Dateisuchfunktionen gefunden und geöffnet werden kann, können Sie auf die geladenen Skripte über die Ansicht **LOADED SCRIPTS** in der Ansicht **Run and Debug** zugreifen

Loaded Scripts Explorer

Die Ansicht **LOADED SCRIPTS** ermöglicht es Ihnen, das Skript schnell auszuwählen, indem Sie seinen Namen eingeben, oder die Liste zu filtern, wenn **Enable Filter on Type** aktiviert ist.

Skripte werden in einen schreibgeschützten Editor geladen, in dem Sie Breakpoints setzen können. Diese Breakpoints werden über Debug-Sitzungen hinweg beibehalten, aber Sie haben nur während einer laufenden Debug-Sitzung Zugriff auf den Skriptinhalt.

Debug-Sitzungen bei Quellcodeänderungen automatisch neu starten

Das Attribut restart einer Startkonfiguration steuert, ob der Node.js-Debugger automatisch neu gestartet wird, nachdem die Debug-Sitzung beendet wurde. Diese Funktion ist nützlich, wenn Sie nodemon verwenden, um Node.js bei Dateiänderungen neu zu starten. Das Setzen des Attributs restart der Startkonfiguration auf true bewirkt, dass der Node-Debugger automatisch versucht, sich erneut an Node.js anzuhängen, nachdem Node.js beendet wurde.

Wenn Sie Ihr Programm server.js über nodemon auf der Befehlszeile wie folgt gestartet haben

nodemon --inspect server.js

können Sie den VS Code-Debugger mit der folgenden Startkonfiguration daran anhängen

{
  "name": "Attach to node",
  "type": "node",
  "request": "attach",
  "restart": true,
  "port": 9229
}

Alternativ können Sie Ihr Programm server.js direkt über nodemon mit einer Startkonfiguration starten und den VS Code-Debugger anhängen

{
  "name": "Launch server.js via nodemon",
  "type": "node",
  "request": "launch",
  "runtimeExecutable": "nodemon",
  "program": "${workspaceFolder}/server.js",
  "console": "integratedTerminal",
  "internalConsoleOptions": "neverOpen"
}

Tipp: Das Drücken der Schaltfläche **Stop** beendet die Debug-Sitzung und trennt die Verbindung zu Node.js, aber **nodemon** (und Node.js) laufen weiter. Um **nodemon** zu beenden, müssen Sie es von der Befehlszeile aus beenden (was leicht möglich ist, wenn Sie integratedTerminal wie oben gezeigt verwenden).

Tipp: Bei Syntaxfehlern kann **nodemon** Node.js erst erfolgreich starten, wenn der Fehler behoben ist. In diesem Fall versucht VS Code weiterhin, sich an Node.js anzuhängen, gibt jedoch schließlich auf (nach 10 Sekunden). Um dies zu vermeiden, können Sie die Timeout-Dauer erhöhen, indem Sie ein Attribut timeout mit einem größeren Wert (in Millisekunden) hinzufügen.

Frame neu starten

Der Node-Debugger unterstützt das Neustarten der Ausführung an einem Stack-Frame. Dies kann in Situationen nützlich sein, in denen Sie ein Problem in Ihrem Quellcode gefunden haben und einen kleinen Teil des Codes mit geänderten Eingabewerten erneut ausführen möchten. Das Stoppen und anschließende Neustarten der vollständigen Debug-Sitzung kann zeitaufwendig sein. Die Aktion **Restart Frame** ermöglicht es Ihnen, die aktuelle Funktion erneut aufzurufen, nachdem Sie Variablen mit der Aktion **Set Value** geändert haben

Restart frame

Restart Frame macht keine Rückgängig-Mutationen am Zustand außerhalb der Funktion, daher funktioniert es möglicherweise nicht immer wie erwartet.

Haltepunkte

Bedingte Breakpoints

Bedingte Breakpoints sind Breakpoints, die nur anhalten, wenn ein Ausdruck einen Wahrheitswert zurückgibt. Sie können einen erstellen, indem Sie mit der rechten Maustaste in den Bereich neben einer Zeilennummer klicken und "Conditional Breakpoint" auswählen

Conditional breakpoint

Log-Haltepunkte

Manchmal möchten Sie eine Nachricht oder einen Wert einfach protokollieren, wenn der Code eine bestimmte Stelle erreicht, anstatt anzuhalten. Sie können dies mit Logpoints tun. Logpoints halten nicht an, sondern protokollieren eine Nachricht in der Debug-Konsole, wenn sie erreicht werden. Im JavaScript-Debugger können Sie geschweifte Klammern verwenden, um Ausdrücke in die Nachricht zu interpolieren, wie z. B. aktueller Wert ist: {meinVariable.eigenschaft}.

Sie können einen erstellen, indem Sie mit der rechten Maustaste auf den Rand neben einer Zeilennummer klicken und "Logpoint" auswählen. Zum Beispiel könnte dies etwas wie Ort ist /usr/local protokollieren.

Logpoint

Breakpoints mit Trefferzahl

Die Bedingung "Trefferzahl" steuert, wie oft ein Breakpoint erreicht werden muss, bevor die Ausführung "unterbrochen" wird. Sie können einen Breakpoint mit Trefferzahl platzieren, indem Sie mit der rechten Maustaste auf den Rand neben einer Zeilennummer klicken, "Bedingter Breakpoint" auswählen und dann zu "Trefferzahl" wechseln.

Hit count breakpoint

Die vom Node.js-Debugger unterstützte Syntax für die Trefferzahl ist entweder eine Ganzzahl oder einer der Operatoren <, <=, ==, >, >=, % gefolgt von einer Ganzzahl.

Einige Beispiele

  • >10 unterbricht immer nach 10 Treffern
  • <3 unterbricht nur bei den ersten beiden Treffern
  • 10 dasselbe wie >=10
  • %2 unterbricht bei jedem zweiten Treffer

Ausgelöste Haltepunkte

Ein ausgelöster Haltepunkt ist ein Haltepunkt, der automatisch aktiviert wird, sobald ein anderer Haltepunkt getroffen wird. Sie können sehr nützlich sein, um Fehlerfälle im Code zu diagnostizieren, die nur nach einer bestimmten Vorbedingung auftreten.

Ausgelöste Haltepunkte können durch Rechtsklick auf den Glyph-Rand gesetzt werden, indem Ausgelösten Haltepunkt hinzufügen ausgewählt und dann gewählt wird, welcher andere Haltepunkt den Haltepunkt aktiviert.

Breakpoint-Validierung

Aus Leistungsgründen analysiert Node.js die Funktionen in JavaScript-Dateien bei der ersten Verwendung verzögert. Folglich funktionieren Breakpoints nicht in Quellcodebereichen, die von Node.js noch nicht gesehen (analysiert) wurden.

Da dieses Verhalten für das Debugging nicht ideal ist, übergibt VS Code automatisch die Option --nolazy an Node.js. Dies verhindert die verzögerte Analyse und stellt sicher, dass Breakpoints vor der Ausführung des Codes validiert werden können (sodass sie nicht mehr "springen").

Da die Option --nolazy die Startzeit des Debug-Ziels erheblich erhöhen kann, können Sie sie einfach deaktivieren, indem Sie --lazy als Attribut runtimeArgs übergeben.

Wenn Sie dies tun, werden Sie feststellen, dass einige Ihrer Breakpoints nicht an der angeforderten Zeile "haften", sondern stattdessen zur nächsten verfügbaren Zeile in bereits analysiertem Code "springen". Um Verwirrung zu vermeiden, zeigt VS Code Breakpoints immer an der Stelle an, an der Node.js den Breakpoint vermutet. Im Abschnitt **BREAKPOINTS** werden diese Breakpoints mit einem Pfeil zwischen der angeforderten und der tatsächlichen Zeilennummer angezeigt.

Breakpoints View

Diese Breakpoint-Validierung erfolgt, wenn eine Sitzung beginnt und die Breakpoints bei Node.js registriert werden, oder wenn eine Sitzung bereits läuft und ein neuer Breakpoint gesetzt wird. In diesem Fall kann der Breakpoint zu einer anderen Stelle "springen". Nachdem Node.js den gesamten Code analysiert hat (z. B. durch Ausführung), können Breakpoints mit der Schaltfläche **Wieder anwenden** im Kopf des Abschnitts **BREAKPOINTS** einfach auf die angeforderten Stellen zurückgesetzt werden. Dies sollte die Breakpoints zur angeforderten Stelle "zurückspringen" lassen.

Breakpoint Actions

Uninteressanten Code überspringen

Das Node.js-Debugging in VS Code verfügt über eine Funktion, um Quellcode zu vermeiden, den Sie nicht durchlaufen möchten (auch bekannt als "Just My Code"). Diese Funktion kann mit dem Attribut skipFiles in Ihrer Startkonfiguration aktiviert werden. skipFiles ist ein Array von Glob-Mustern für zu überspringende Skriptpfade.

Zum Beispiel wird mit

  "skipFiles": [
    "${workspaceFolder}/node_modules/**/*.js",
    "${workspaceFolder}/lib/**/*.js"
  ]

jeglicher Code in den Ordnern node_modules und lib Ihres Projekts übersprungen. Die skipFiles gelten auch für den Ort, der beim Aufruf von console.log und ähnlichen Methoden angezeigt wird: Der erste nicht übersprungene Ort im Stapel wird neben der Ausgabe in der Debug-Konsole angezeigt.

Integrierte **Core-Module** von Node.js können mit dem 'magischen Namen' <node_internals> in Glob-Mustern referenziert werden. Das folgende Beispiel überspringt alle internen Module.

  "skipFiles": [
     "<node_internals>/**/*.js"
   ]

Die genauen Regeln für das "Überspringen" lauten wie folgt:

  • Wenn Sie in eine übersprungene Datei hineinspringen, werden Sie dort nicht anhalten – Sie werden bei der nächsten ausgeführten Zeile anhalten, die nicht in einer übersprungenen Datei liegt.
  • Wenn Sie die Option zum Unterbrechen bei ausgelösten Ausnahmen gesetzt haben, werden Sie bei Ausnahmen, die aus übersprungenen Dateien ausgelöst werden, nicht unterbrechen, es sei denn, sie blubbern in eine nicht übersprungene Datei auf.
  • Wenn Sie einen Breakpoint in einer übersprungenen Datei setzen, werden Sie an diesem Breakpoint anhalten und können ihn durchlaufen, bis Sie ihn verlassen, an welchem Punkt das normale Überspringverhalten wieder aufgenommen wird.
  • Der Ort von Konsolenmeldungen aus übersprungenen Dateien wird als erster nicht übersprungener Ort im Aufrufstapel angezeigt.

Übersprungener Quellcode wird in der Ansicht **CALL STACK** in einem 'gedämpften' Stil angezeigt.

Skipped source is dimmed in call stack view

Wenn Sie mit der Maus über die gedämpften Einträge fahren, wird erklärt, warum der Stapelrahmen gedämpft ist.

Ein Kontextmenüelement im Aufrufstapel, **Überspringen dieser Datei umschalten**, ermöglicht es Ihnen, eine Datei zur Laufzeit einfach zu überspringen, ohne sie Ihrer Startkonfiguration hinzuzufügen. Diese Option gilt nur für die aktuelle Debug-Sitzung. Sie können sie auch verwenden, um das Überspringen einer Datei zu beenden, die von der Option skipFiles in Ihrer Startkonfiguration übersprungen wird.

Hinweis: Der Debugger des legacy-Protokolls unterstützt negative Glob-Muster, diese müssen jedoch einem positiven Muster **folgen**: Positive Muster fügen der Menge der übersprungenen Dateien hinzu, während negative Muster aus dieser Menge subtrahieren.

Im folgenden (nur legacy-Protokoll-) Beispiel wird alles bis auf ein 'math'-Modul übersprungen.

"skipFiles": [
    "${workspaceFolder}/node_modules/**/*.js",
    "!${workspaceFolder}/node_modules/math/**/*.js"
]

Hinweis: Der Debugger des legacy-Protokolls muss die skipFiles-Funktion emulieren, da das **V8 Debugger Protocol** diese nicht nativ unterstützt. Dies kann zu einer langsamen Schrittausführung führen.

WebAssembly debuggen

Der JavaScript-Debugger kann in WebAssembly kompilierte Codes debuggen, wenn dieser DWARF-Debug-Informationen enthält. Viele Toolchains unterstützen die Erzeugung dieser Informationen.

  • C/C++ mit Emscripten: Kompilieren Sie mit dem Flag -g, um Debug-Informationen zu erzeugen.
  • Zig: DWARF-Informationen werden im "Debug"-Build-Modus automatisch erzeugt.
  • Rust: Rust erzeugt DWARF-Debug-Informationen. Allerdings behält wasm-pack noch nicht diese während des Builds. Anstatt also wasm-pack build auszuführen, sollten Benutzer der gängigen wasm-bindgen/wasm-pack-Bibliotheken manuell mit zwei Befehlen builden.
    1. cargo install wasm-bindgen-cli einmal, um das notwendige Kommandozeilen-Tool zu installieren.
    2. cargo build --target wasm32-unknown-unknown, um Ihre Bibliothek zu bauen.
    3. wasm-bindgen --keep-debug --out-dir pkg ./target/wasm32-unknown-unknown/debug/<library-name>.wasm <extra-arguments>, um die WebAssembly-Bindings zu generieren, wobei <library-name> durch den Namen aus Ihrer Cargo.toml ersetzt und <extra-arguments> nach Bedarf konfiguriert werden.

Nachdem Ihr Code kompiliert ist, sollten Sie die Erweiterung WebAssembly DWARF Debugging installieren. Diese wird als separate Erweiterung ausgeliefert, um den VS Code-Kern "stromlinienförmig" zu halten. Nach der Installation starten Sie alle aktiven Debug-Sitzungen neu, und der native Code sollte im Debugger abgebildet sein! Sie sollten Ihren Quellcode in der Ansicht **Loaded Sources** sehen, und Breakpoints sollten funktionieren.

Im folgenden Bild ist der Debugger auf einem Breakpoint in C++-Quellcode gestoppt, der ein Mandelbrot-Fraktal erzeugt. Der Aufrufstapel ist sichtbar, mit Frames vom JavaScript-Code über WebAssembly bis hin zum zugeordneten C++-Code. Sie können auch die Variablen im C++-Code und eine Änderung im Speicher sehen, die der int32-Variable height zugeordnet ist.

Debugger stopped on a breakpoint in C++ source code

Obwohl es fast gleichwertig ist, ist das Debuggen von WebAssembly etwas anders als das gewöhnliche JavaScript.

  • Variablen in der Ansicht **Variables** können nicht direkt bearbeitet werden. Sie können jedoch die Aktion **View Binary Data** neben der Variable auswählen, um ihren zugeordneten Speicher zu bearbeiten.
  • Grundlegende Ausdrucksauswertung in den Ansichten **Debug Console** und **Watch** wird von lldb-eval bereitgestellt. Dies unterscheidet sich von gewöhnlichen JavaScript-Ausdrücken.
  • Orte, die keiner Quellcodezuordnung entsprechen, werden im disassemblierten WebAssembly Text Format angezeigt. Für WebAssembly bewirkt der Befehl **Disable Source Map Stepping**, dass der Debugger nur im disassemblierten Code Schritte ausführt.

Das WebAssembly-Debugging von VS Code basiert auf der C/C++ Debugging Extension der Chromium-Autoren.

Unterstützte Node-ähnliche Laufzeiten

Der aktuelle JavaScript-Debugger von VS Code unterstützt Node-Versionen ab 8.x, aktuelle Chrome-Versionen und aktuelle Edge-Versionen (über den msedge-Starttyp).

Nächste Schritte

Falls Sie den Node.js-Abschnitt noch nicht gelesen haben, schauen Sie sich Folgendes an:

  • Node.js - End-to-End-Node-Szenario mit einer Beispielanwendung.

Ein Tutorial zu den Grundlagen des Debuggens in VS Code finden Sie in diesem Video:

Informationen zur Unterstützung von VS Code bei der Ausführung von Aufgaben finden Sie unter:

  • Tasks - Ausführen von Tasks mit Gulp, Grunt und Jake. Anzeigen von Fehlern und Warnungen.

Um Ihre eigene Debugger-Erweiterung zu schreiben, besuchen Sie:

  • Debugger-Erweiterung - Schritte zur Erstellung einer VS Code Debugger-Erweiterung, beginnend mit einem Mock-Beispiel.

Häufig gestellte Fragen

Kann ich debuggen, wenn ich Symlinks verwende?

Ja, wenn Sie Symlinks für Ordner innerhalb Ihres Projekts erstellt haben, z. B. mit npm link, können Sie die symlinkten Quellen debuggen, indem Sie die Node.js-Laufzeit anweisen, Symlink-Pfade zu erhalten. Verwenden Sie den --preserve-symlinks Switch von node.exe in Ihrer runtimeArgs-Attribut der Startkonfiguration. runtimeArgs, ein Array von Zeichenketten, werden an die Laufzeit-Executable der Debugging-Sitzung übergeben, die standardmäßig node.exe ist.

{
  "runtimeArgs": ["--preserve-symlinks"]
}

Wenn Ihr Hauptskript sich innerhalb eines symlinkten Pfads befindet, müssen Sie auch die Option "--preserve-symlinks-main" hinzufügen. Diese Option ist nur in Node 10+ verfügbar.

Wie debugge ich ECMAScript-Module?

Wenn Sie esm verwenden oder --experimental-modules an Node.js übergeben, um ECMAScript-Module zu verwenden, können Sie diese Optionen über das Attribut runtimeArgs von launch.json übergeben.

Wie kann ich NODE_OPTIONS setzen?

Der Debugger verwendet die spezielle Umgebungsvariable NODE_OPTIONS, um das Debugging mit Ihrer Anwendung einzurichten, und deren Überschreibung verhindert, dass das Debugging korrekt funktioniert. Anstatt sie zu überschreiben, sollten Sie sie anhängen. Zum Beispiel könnte eine .bashrc-Datei etwas wie folgt enthalten:

export NODE_OPTIONS="$NODE_OPTIONS --some-other-option=here"
12/10/2025
© . This site is unofficial and not affiliated with Microsoft.