Debugging
Diese Dokumentation erklärt, wie du deinen Next.js-Frontend- und Backend-Code mit vollständiger Quellcode-Mapping-Unterstützung mithilfe des VS Code-Debuggers oder Chrome DevTools debuggen kannst.
Jeder Debugger, der an Node.js angehängt werden kann, kann auch zum Debuggen einer Next.js-Anwendung verwendet werden. Weitere Details findest du im Node.js Debugging-Leitfaden.
Debugging mit VS Code
Erstelle eine Datei mit dem Namen .vscode/launch.json im Stammverzeichnis deines Projekts mit folgendem Inhalt:
{
"version": "0.2.0",
"configurations": [
{
"name": "Next.js: Server-seitiges Debugging",
"type": "node-terminal",
"request": "launch",
"command": "npm run dev"
},
{
"name": "Next.js: Client-seitiges Debugging",
"type": "chrome",
"request": "launch",
"url": "http://localhost:3000"
},
{
"name": "Next.js: Full-Stack-Debugging",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/node_modules/.bin/next",
"runtimeArgs": ["--inspect"],
"skipFiles": ["<node_internals>/**"],
"serverReadyAction": {
"action": "debugWithEdge",
"killOnServerStop": true,
"pattern": "- Local:.+(https?://.+)",
"uriFormat": "%s",
"webRoot": "${workspaceFolder}"
}
}
]
}npm run dev kann durch yarn dev ersetzt werden, wenn du Yarn verwendest, oder durch pnpm dev, wenn du pnpm verwendest.
Wenn du die Portnummer änderst, unter der deine Anwendung startet, ersetze die 3000 in http://localhost:3000 mit dem Port, den du verwendest.
Wenn du Next.js aus einem anderen Verzeichnis als dem Stammverzeichnis ausführst (beispielsweise bei Verwendung von Turborepo), musst du cwd zu den Server-seitigen und Full-Stack-Debugging-Aufgaben hinzufügen. Zum Beispiel "cwd": "${workspaceFolder}/apps/web".
Gehe nun zum Debugging-Panel (Strg+Umschalt+D unter Windows/Linux, ⇧+⌘+D unter macOS), wähle eine Startkonfiguration und drücke F5 oder wähle Debug: Debugging starten aus der Befehlspalette, um deine Debugging-Sitzung zu starten.
Verwendung des Debuggers in Jetbrains WebStorm
Klicke auf das Dropdown-Menü mit den Laufzeit-Konfigurationen und klicke auf Konfigurationen bearbeiten.... Erstelle eine JavaScript-Debugging-Konfiguration mit http://localhost:3000 als URL. Passe sie nach Belieben an (z.B. Browser zum Debuggen, als Projektdatei speichern) und klicke auf OK. Führe diese Debugging-Konfiguration aus, und der ausgewählte Browser sollte automatisch geöffnet werden. An diesem Punkt solltest du 2 Anwendungen im Debugmodus haben: die NextJS-Node-Anwendung und die Client-/Browser-Anwendung.
Debugging mit Chrome DevTools
Client-seitiger Code
Starte deinen Entwicklungsserver wie üblich, indem du next dev, npm run dev oder yarn dev ausführst. Sobald der Server gestartet ist, öffne http://localhost:3000 (oder deine alternative URL) in Chrome. Öffne dann die Chrome-Entwicklertools (Strg+Umschalt+J unter Windows/Linux, ⌥+⌘+I unter macOS) und gehe zur Registerkarte Quellen.
Jedes Mal, wenn dein Client-seitiger Code eine debugger-Anweisung erreicht, wird die Codeausführung angehalten und diese Datei erscheint im Debug-Bereich. Du kannst auch Strg+P unter Windows/Linux oder ⌘+P unter macOS drücken, um eine Datei zu suchen und Breakpoints manuell zu setzen. Beachte, dass die Pfade deiner Quelldateien hier mit webpack://_N_E/./ beginnen.
Server-seitiger Code
Um Server-seitigen Next.js-Code mit Chrome DevTools zu debuggen, musst du das Flag --inspect an den zugrunde liegenden Node.js-Prozess übergeben:
NODE_OPTIONS='--inspect' next devWenn du npm run dev oder yarn dev verwendest, solltest du das dev-Skript in deiner package.json aktualisieren:
{
"scripts": {
"dev": "NODE_OPTIONS='--inspect' next dev"
}
}Das Starten des Next.js-Entwicklungsservers mit dem --inspect-Flag wird etwa so aussehen:
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:3000Sobald der Server gestartet ist, öffne einen neuen Tab in Chrome und besuche chrome://inspect, wo du deine Next.js-Anwendung im Abschnitt Remote Target sehen solltest. Klicke auf inspect unter deiner Anwendung, um ein separates DevTools-Fenster zu öffnen, und gehe dann zur Registerkarte Quellen.
Das Debugging von Server-seitigem Code funktioniert hier ähnlich wie das Debuggen von Client-seitigem Code mit Chrome DevTools, außer dass die Pfade deiner Quelldateien bei der Suche mit Strg+P oder ⌘+P mit webpack://{Anwendungsname}/./ beginnen (wobei {Anwendungsname} durch den Namen deiner Anwendung laut package.json-Datei ersetzt wird).
Server-Fehler mit Chrome DevTools untersuchen
Wenn du auf einen Fehler stößt, kann das Untersuchen des Quellcodes helfen, die Ursache von Fehlern zu verfolgen.
Next.js zeigt ein Node.js-Logo wie einen grünen Button in der Entwickler-Overlay an. Durch Klicken dieses Buttons wird die Chrome DevTool-URL in die Zwischenablage kopiert, und du kannst einen neuen Browser-Tab mit dieser URL öffnen, um den Next.js-Serverprozess mit Chrome DevTool 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, installiere das Paket cross-env als Entwicklungsabhängigkeit (-D mit npm und yarn) und ersetze das dev-Skript durch Folgendes:
{
"scripts": {
"dev": "cross-env NODE_OPTIONS='--inspect' next dev"
}
}cross-env wird die NODE_OPTIONS-Umgebungsvariable unabhängig von der Plattform (einschließlich Mac, Linux und Windows) festlegen und ermöglicht dir ein konsistentes Debugging auf verschiedenen Geräten und Betriebssystemen.
Hinweis: Stelle sicher, dass Windows Defender auf deinem Gerät deaktiviert ist. Dieser externe Dienst überprüft jede gelesene Datei, was nachweislich die Fast Refresh-Zeit mit
next devstark erhöht. Dies ist ein bekanntes Problem, das nicht mit Next.js zusammenhängt, aber Next.js-Entwicklung beeinträchtigt.
Weitere Informationen
Weitere Informationen zur Verwendung eines JavaScript-Debuggers findest du in der folgenden Dokumentation: