Débogage

Cette documentation explique comment déboguer votre code frontend et backend Next.js avec le support complet des source maps, en utilisant soit le débogueur VS Code, soit Chrome DevTools.

Tout débogueur capable de se connecter à Node.js peut également être utilisé pour déboguer une application Next.js. Vous trouverez plus de détails dans le Guide de débogage de Node.js.

Débogage avec VS Code

Créez un fichier nommé .vscode/launch.json à la racine de votre projet avec le contenu suivant :

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 peut être remplacé par yarn dev si vous utilisez Yarn ou pnpm dev si vous utilisez pnpm.

Si vous modifiez le numéro de port sur lequel votre application démarre, remplacez le 3000 dans http://localhost:3000 par le port que vous utilisez.

Si vous exécutez Next.js depuis un répertoire autre que la racine (par exemple, si vous utilisez Turborepo), vous devez ajouter cwd aux tâches de débogage côté serveur et full stack. Par exemple, "cwd": "${workspaceFolder}/apps/web".

Allez maintenant dans le panneau Debug (Ctrl+Shift+D sur Windows/Linux, ⇧+⌘+D sur macOS), sélectionnez une configuration de lancement, puis appuyez sur F5 ou sélectionnez Debug: Start Debugging dans la Palette de commandes pour démarrer votre session de débogage.

Utilisation du débogueur dans Jetbrains WebStorm

Cliquez sur le menu déroulant listant les configurations d'exécution, puis cliquez sur Edit Configurations.... Créez une configuration de débogage Javascript Debug avec http://localhost:3000 comme URL. Personnalisez selon vos préférences (par exemple, navigateur pour le débogage, enregistrer comme fichier de projet), puis cliquez sur OK. Exécutez cette configuration de débogage, et le navigateur sélectionné devrait s'ouvrir automatiquement. À ce stade, vous devriez avoir 2 applications en mode débogage : l'application node NextJS et l'application client/navigateur.

Débogage avec Chrome DevTools

Code côté client

Démarrez votre serveur de développement comme d'habitude en exécutant next dev, npm run dev ou yarn dev. Une fois le serveur démarré, ouvrez http://localhost:3000 (ou votre URL alternative) dans Chrome. Ensuite, ouvrez les Outils de développement de Chrome (Ctrl+Shift+J sur Windows/Linux, ⌥+⌘+I sur macOS), puis allez dans l'onglet Sources.

Désormais, chaque fois que votre code côté client atteint une instruction debugger, l'exécution du code sera suspendue et ce fichier apparaîtra dans la zone de débogage. Vous pouvez également appuyer sur Ctrl+P sur Windows/Linux ou ⌘+P sur macOS pour rechercher un fichier et définir des points d'arrêt manuellement. Notez que lors de cette recherche, vos fichiers sources auront des chemins commençant par webpack://_N_E/./.

Code côté serveur

Pour déboguer le code serveur Next.js avec Chrome DevTools, vous devez passer le flag --inspect au processus Node.js sous-jacent :

Terminal

NODE_OPTIONS='--inspect' next dev

Si vous utilisez npm run dev ou yarn dev, vous devez mettre à jour le script dev dans votre package.json :

package.json

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

Le lancement du serveur de développement Next.js avec le flag --inspect ressemblera à ceci :

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

Notez que l'exécution de NODE_OPTIONS='--inspect' npm run dev ou NODE_OPTIONS='--inspect' yarn dev ne fonctionnera pas. Cela essaierait de démarrer plusieurs débogueurs sur le même port : un pour le processus npm/yarn et un pour Next.js. Vous obtiendriez alors une erreur comme Starting inspector on 127.0.0.1:9229 failed: address already in use dans votre console.

Une fois le serveur démarré, ouvrez un nouvel onglet dans Chrome et visitez chrome://inspect, où vous devriez voir votre application Next.js dans la section Cibles distantes. Cliquez sur inspecter sous votre application pour ouvrir une fenêtre DevTools séparée, puis allez dans l'onglet Sources.

Le débogage du code serveur fonctionne ici comme le débogage du code client avec Chrome DevTools, sauf que lorsque vous recherchez des fichiers ici avec Ctrl+P ou ⌘+P, vos fichiers sources auront des chemins commençant par webpack://{nom-de-l'application}/./ (où {nom-de-l'application} sera remplacé par le nom de votre application selon votre fichier package.json).

Débogage sur Windows

Les utilisateurs Windows peuvent rencontrer un problème lors de l'utilisation de NODE_OPTIONS='--inspect' car cette syntaxe n'est pas supportée sur les plateformes Windows. Pour contourner ce problème, installez le package cross-env comme dépendance de développement (-D avec npm et yarn) et remplacez le script dev par ce qui suit.

package.json

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

cross-env définira la variable d'environnement NODE_OPTIONS quelle que soit la plateforme (y compris Mac, Linux et Windows) et vous permettra de déboguer de manière cohérente sur tous les appareils et systèmes d'exploitation.

Bon à savoir : Assurez-vous que Windows Defender est désactivé sur votre machine. Ce service externe vérifie chaque fichier lu, ce qui a été signalé comme augmentant considérablement le temps de Fast Refresh avec next dev. Il s'agit d'un problème connu, non lié à Next.js, mais qui affecte le développement avec Next.js.

Plus d'informations

Pour en savoir plus sur l'utilisation d'un débogueur JavaScript, consultez la documentation suivante :