Debugging

Diese Dokumentation erklärt, wie Sie Ihren Next.js-Frontend- und Backend-Code mit voller Unterstützung für Source Maps debuggen können, entweder mit dem VS Code-Debugger oder Chrome DevTools.

Jeder Debugger, der sich an Node.js anhängen kann, kann auch zum Debuggen einer Next.js-Anwendung verwendet werden. Weitere Details finden Sie im Debugging Guide von Node.js.

Debugging mit VS Code

Erstellen Sie eine Datei namens .vscode/launch.json im Stammverzeichnis Ihres Projekts mit folgendem Inhalt:

launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

npm run dev kann durch yarn dev ersetzt werden, wenn Sie Yarn verwenden, oder durch pnpm dev bei Verwendung von pnpm.

Wenn Sie die Portnummer ändern, auf der Ihre Anwendung startet, ersetzen Sie 3000 in http://localhost:3000 durch den von Ihnen verwendeten Port.

Wenn Sie Next.js aus einem anderen Verzeichnis als dem Stammverzeichnis ausführen (z.B. bei Verwendung von Turborepo), müssen Sie cwd zu den Debugging-Tasks für die Server-seitige und Full-Stack-Debugging hinzufügen. Beispiel: "cwd": "${workspaceFolder}/apps/web".

Gehen Sie nun zum Debug-Panel (Strg+Umschalt+D unter Windows/Linux, ⇧+⌘+D unter macOS), wählen Sie eine Launch-Konfiguration aus und drücken Sie F5 oder wählen Sie Debug: Start Debugging aus der Befehlspalette, um Ihre Debugging-Sitzung zu starten.

Verwendung des Debuggers in Jetbrains WebStorm

Klicken Sie auf das Dropdown-Menü mit den Laufzeitkonfigurationen und wählen Sie Edit Configurations.... Erstellen Sie eine Javascript Debug-Debug-Konfiguration mit http://localhost:3000 als URL. Passen Sie sie nach Belieben an (z.B. Browser für das Debugging, Speichern als Projektdatei) und klicken Sie auf OK. Führen Sie diese Debug-Konfiguration aus, und der ausgewählte Browser sollte automatisch geöffnet werden. Zu diesem Zeitpunkt sollten Sie zwei Anwendungen im Debug-Modus haben: die NextJS-Node-Anwendung und die Client-/Browser-Anwendung.

Debugging mit Chrome DevTools

Client-seitiger Code

Starten Sie Ihren Entwicklungsserver wie gewohnt mit next dev, npm run dev oder yarn dev. Sobald der Server gestartet ist, öffnen Sie http://localhost:3000 (oder Ihre alternative URL) in Chrome. Öffnen Sie dann die Developer Tools von Chrome (Strg+Umschalt+J unter Windows/Linux, ⌥+⌘+I unter macOS) und gehen Sie zum Tab Sources.

Jedes Mal, wenn Ihr Client-seitiger Code auf eine debugger-Anweisung trifft, wird die Codeausführung angehalten und die Datei erscheint im Debug-Bereich. Sie können auch Strg+P unter Windows/Linux oder ⌘+P unter macOS drücken, um nach einer Datei zu suchen und manuell Breakpoints zu setzen. Beachten Sie, dass Ihre Quelldateien hier Pfade haben, die mit webpack://_N_E/./ beginnen.

Server-seitiger Code

Um server-seitigen Next.js-Code mit Chrome DevTools zu debuggen, müssen Sie das --inspect-Flag an den zugrunde liegenden Node.js-Prozess übergeben:

Terminal

NODE_OPTIONS='--inspect' next dev

Wenn Sie npm run dev oder yarn dev verwenden, sollten Sie das dev-Skript in Ihrer package.json aktualisieren:

package.json

{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next dev"
  }
}

Das Starten des Next.js-Dev-Servers mit dem --inspect-Flag sieht etwa so aus:

Terminal

Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Beachten Sie, dass NODE_OPTIONS='--inspect' npm run dev oder NODE_OPTIONS='--inspect' yarn dev nicht funktionieren wird. Dies würde versuchen, mehrere Debugger auf demselben Port zu starten: einen für den npm/yarn-Prozess und einen für Next.js. Sie würden dann eine Fehlermeldung wie Starting inspector on 127.0.0.1:9229 failed: address already in use in Ihrer Konsole sehen.

Sobald der Server gestartet ist, öffnen Sie einen neuen Tab in Chrome und besuchen Sie chrome://inspect, wo Sie Ihre Next.js-Anwendung im Abschnitt Remote Target sehen sollten. Klicken Sie auf inspect unter Ihrer Anwendung, um ein separates DevTools-Fenster zu öffnen, und gehen Sie dann zum Tab Sources.

Das Debugging von server-seitigem Code funktioniert hier ähnlich wie das Debugging von client-seitigem Code mit Chrome DevTools, mit dem Unterschied, dass Ihre Quelldateien hier Pfade haben, die mit webpack://{application-name}/./ beginnen (wobei {application-name} durch den Namen Ihrer Anwendung gemäß Ihrer package.json-Datei ersetzt wird).

Debugging unter Windows

Windows-Benutzer können auf ein Problem stoßen, wenn sie NODE_OPTIONS='--inspect' verwenden, da diese Syntax auf Windows-Plattformen nicht unterstützt wird. Um dies zu umgehen, installieren Sie das Paket cross-env als Entwicklungsabhängigkeit (-D mit npm und yarn) und ersetzen Sie das dev-Skript durch Folgendes:

package.json

{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS='--inspect' next dev"
  }
}

cross-env setzt die Umgebungsvariable NODE_OPTIONS unabhängig von der Plattform (einschließlich Mac, Linux und Windows) und ermöglicht Ihnen ein konsistentes Debugging über Geräte und Betriebssysteme hinweg.

Gut zu wissen: Stellen Sie sicher, dass Windows Defender auf Ihrem Computer deaktiviert ist. Dieser externe Dienst überprüft jede gelesene Datei, was bekanntermaßen die Fast-Refresh-Zeit mit next dev erheblich erhöht. Dies ist ein bekanntes Problem, das nicht spezifisch für Next.js ist, aber die Next.js-Entwicklung beeinflusst.

Weitere Informationen

Um mehr über die Verwendung eines JavaScript-Debuggers zu erfahren, lesen Sie die folgende Dokumentation: