Verwendung von Debugging-Tools mit Next.js

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

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-Leitfaden 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 client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

Hinweis: Um Firefox-Debugging in VS Code zu verwenden, müssen Sie die Firefox Debugger-Erweiterung installieren.

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

In der Konfiguration "Next.js: debug full stack" gibt serverReadyAction.action an, welcher Browser geöffnet werden soll, wenn der Server bereit ist. debugWithEdge bedeutet, dass der Edge-Browser gestartet wird. Wenn Sie Chrome verwenden, ändern Sie diesen Wert in debugWithChrome.

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. wenn Sie Turborepo verwenden), müssen Sie cwd zu den Debugging-Aufgaben für die Server- und Full-Stack-Seite hinzufügen. Zum Beispiel: "cwd": "${workspaceFolder}/apps/web".

Gehen Sie nun zum Debug-Panel (Strg+Umschalt+D unter Windows/Linux, ⇧+⌘+D unter macOS), wählen Sie eine Startkonfiguration 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 Browser 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 Ihrem bevorzugten Browser.

Für Chrome:

Öffnen Sie die Developer Tools von Chrome (Strg+Umschalt+J unter Windows/Linux, ⌥+⌘+I unter macOS)
Gehen Sie zum Tab Sources

Für Firefox:

Öffnen Sie die Developer Tools von Firefox (Strg+Umschalt+I unter Windows/Linux, ⌥+⌘+I unter macOS)
Gehen Sie zum Tab Debugger

In beiden Browsern wird die Codeausführung angehalten, wenn Ihr client-seitiger Code eine debugger-Anweisung erreicht, und die Datei wird im Debug-Bereich angezeigt. Sie können auch nach Dateien suchen, um manuell Breakpoints zu setzen:

In Chrome: Drücken Sie Strg+P unter Windows/Linux oder ⌘+P unter macOS
In Firefox: Drücken Sie Strg+P unter Windows/Linux oder ⌘+P unter macOS oder verwenden Sie die Dateistruktur im linken Panel

Beachten Sie, dass Ihre Quelldateien beim Suchen Pfade haben, die mit webpack://_N_E/./ beginnen.

Server-seitiger Code

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

Terminal

NODE_OPTIONS='--inspect' next dev

Gut zu wissen: Verwenden Sie NODE_OPTIONS='--inspect=0.0.0.0', um den Remote-Debugging-Zugriff außerhalb von localhost zu ermöglichen, z. B. wenn die App in einem Docker-Container läuft.

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 ungefähr 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

Für Chrome:

Öffnen Sie einen neuen Tab und rufen Sie chrome://inspect auf
Klicken Sie auf Configure..., um sicherzustellen, dass beide Debugging-Ports aufgelistet sind
Fügen Sie sowohl localhost:9229 als auch localhost:9230 hinzu, falls sie noch nicht vorhanden sind
Suchen Sie nach Ihrer Next.js-Anwendung im Abschnitt Remote Target
Klicken Sie auf inspect, um ein separates DevTools-Fenster zu öffnen
Gehen Sie zum Tab Sources

Für Firefox:

Öffnen Sie einen neuen Tab und rufen Sie about:debugging auf
Klicken Sie in der linken Seitenleiste auf This Firefox
Unter Remote Targets finden Sie Ihre Next.js-Anwendung
Klicken Sie auf Inspect, um den Debugger zu öffnen
Gehen Sie zum Tab Debugger

Das Debugging von server-seitigem Code funktioniert ähnlich wie client-seitiges Debugging. Beim Suchen nach Dateien (Strg+P/⌘+P) haben Ihre Quelldateien Pfade, die mit webpack://{application-name}/./ beginnen (wobei {application-name} durch den Namen Ihrer Anwendung gemäß Ihrer package.json-Datei ersetzt wird).

Überprüfung von Server-Fehlern mit Browser DevTools

Wenn Sie auf einen Fehler stoßen, kann die Überprüfung des Quellcodes helfen, die Ursache des Fehlers nachzuvollziehen.

Next.js zeigt ein Node.js-Symbol unter der Next.js-Versionsanzeige im Fehler-Overlay an. Durch Klicken auf dieses Symbol wird die DevTools-URL in Ihre Zwischenablage kopiert. Sie können einen neuen Browser-Tab mit dieser URL öffnen, um den Next.js-Server-Prozess zu untersuchen.

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 laut Berichten die Fast-Refresh-Zeit mit next dev erheblich erhöht. Dies ist ein bekanntes Problem, das nicht direkt mit Next.js zusammenhängt, aber die Next.js-Entwicklung beeinflusst.

Weitere Informationen

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

Verwendung von Debugging-Tools mit Next.js

On this page