Débogage de Node.js
Ce guide vous aidera à démarrer le débogage de vos applications et scripts Node.js.
Activer l'inspecteur
Lorsqu'il est lancé avec l'option --inspect, un processus Node.js écoute un client de débogage. Par défaut, il écoute à l'hôte et au port 127.0.0.1:9229. Chaque processus se voit également attribuer un UUID unique.
Les clients de l'inspecteur doivent connaître et spécifier l'adresse de l'hôte, le port et l'UUID pour se connecter. Une URL complète ressemblera à ceci : ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.
Node.js commencera également à écouter les messages de débogage s'il reçoit un signal SIGUSR1. (SIGUSR1 n'est pas disponible sous Windows.) Dans Node.js 7 et les versions antérieures, cela active l'API de débogueur héritée. Dans Node.js 8 et les versions ultérieures, il activera l'API de l'inspecteur.
Implications de sécurité
Étant donné que le débogueur a un accès complet à l'environnement d'exécution Node.js, un acteur malveillant capable de se connecter à ce port peut être capable d'exécuter du code arbitraire au nom du processus Node.js. Il est important de comprendre les implications de sécurité de l'exposition du port du débogueur sur les réseaux publics et privés.
Exposer publiquement le port de débogage est dangereux
Si le débogueur est lié à une adresse IP publique, ou à 0.0.0.0, tous les clients pouvant atteindre votre adresse IP pourront se connecter au débogueur sans aucune restriction et pourront exécuter du code arbitraire.
Par défaut, node --inspect se lie à 127.0.0.1. Vous devez explicitement fournir une adresse IP publique ou 0.0.0.0, etc., si vous souhaitez autoriser les connexions externes au débogueur. Cela peut vous exposer à une menace de sécurité potentiellement importante. Nous vous suggérons de vous assurer que des pare-feu et des contrôles d'accès appropriés sont en place pour éviter une faille de sécurité.
Voir la section sur 'Activer les scénarios de débogage à distance' pour obtenir des conseils sur la manière d'autoriser en toute sécurité les clients de débogueur distants à se connecter.
Les applications locales ont un accès complet à l'inspecteur
Même si vous liez le port de l'inspecteur à 127.0.0.1 (la valeur par défaut), toutes les applications s'exécutant localement sur votre machine auront un accès sans restriction. Ceci est voulu pour permettre aux débogueurs locaux de se connecter facilement.
Navigateurs, WebSockets et politique de même origine
Les sites web ouverts dans un navigateur web peuvent effectuer des requêtes WebSocket et HTTP sous le modèle de sécurité du navigateur. Une connexion HTTP initiale est nécessaire pour obtenir un identifiant de session de débogage unique. La politique de même origine empêche les sites web d'établir cette connexion HTTP. Pour une sécurité accrue contre les attaques par reliaison DNS, Node.js vérifie que les en-têtes 'Host' de la connexion spécifient précisément une adresse IP ou localhost.
Ces politiques de sécurité interdisent la connexion à un serveur de débogage distant en spécifiant le nom d'hôte. Vous pouvez contourner cette restriction en spécifiant soit l'adresse IP, soit en utilisant des tunnels SSH comme décrit ci-dessous.
Clients de l'inspecteur
Un débogueur CLI minimal est disponible avec node inspect myscript.js. Plusieurs outils commerciaux et open source peuvent également se connecter à l'inspecteur Node.js.
Chrome DevTools 55+, Microsoft Edge
- Option 1 : Ouvrez
chrome://inspectdans un navigateur basé sur Chromium ouedge://inspectdans Edge. Cliquez sur le bouton Configurer et assurez-vous que votre hôte et port cible sont listés. - Option 2 : Copiez l'
devtoolsFrontendUrldepuis la sortie de/json/list(voir ci-dessus) ou le texte d'indication--inspectet collez-le dans Chrome.
Voir https://github.com/ChromeDevTools/devtools-frontend, https://www.microsoftedgeinsider.com pour plus d'informations.
Visual Studio Code 1.10+
- Dans le panneau Débogage, cliquez sur l'icône des paramètres pour ouvrir
.vscode/launch.json. Sélectionnez "Node.js" pour la configuration initiale.
Voir https://github.com/microsoft/vscode pour plus d'informations.
JetBrains WebStorm et autres IDE JetBrains
- Créez une nouvelle configuration de débogage Node.js et cliquez sur Déboguer.
--inspectsera utilisé par défaut pour Node.js 7+. Pour désactiver, décochezjs.debugger.node.use.inspectdans le Registre de l'IDE. Pour en savoir plus sur l'exécution et le débogage de Node.js dans WebStorm et les autres IDE JetBrains, consultez l'aide en ligne de WebStorm.
chrome-remote-interface
- Bibliothèque facilitant les connexions aux points de terminaison du protocole Inspector. Voir https://github.com/cyrus-and/chrome-remote-interface pour plus d'informations.
Gitpod
- Démarrez une configuration de débogage Node.js depuis la vue « Débogage » ou appuyez sur
F5. Instructions détaillées
Voir https://www.gitpod.io pour plus d'informations.
Eclipse IDE avec l'extension Eclipse Wild Web Developer
- À partir d'un fichier
.js, choisissezDéboguer en tant que... > Programme Node, ou créez une configuration de débogage pour attacher le débogueur à l'application Node.js en cours d'exécution (déjà démarrée avec--inspect).
Voir https://eclipse.org/eclipseide pour plus d'informations.
Options de ligne de commande
Le tableau suivant répertorie l'impact de différents indicateurs d'exécution sur le débogage :
| Indicateur | Signification |
|---|---|
--inspect | Active le débogage avec l'inspecteur Node.js. Écoute sur l'adresse et le port par défaut (127.0.0.1:9229) |
--inspect-brk | Active le débogage avec l'inspecteur Node.js. Écoute sur l'adresse et le port par défaut (127.0.0.1:9229) ; interruption avant le démarrage du code utilisateur |
--inspect=[host:port] | Active l'agent inspecteur ; lie à l'adresse ou au nom d'hôte host (par défaut : 127.0.0.1) ; écoute sur le port port (par défaut : 9229) |
--inspect-brk=[host:port] | Active l'agent inspecteur ; lie à l'adresse ou au nom d'hôte host (par défaut : 127.0.0.1) ; écoute sur le port port (par défaut : 9229) ; interruption avant le démarrage du code utilisateur |
--inspect-wait | Active l'agent inspecteur ; écoute sur l'adresse et le port par défaut (127.0.0.1:9229) ; attend que le débogueur soit attaché. |
--inspect-wait=[host:port] | Active l'agent inspecteur ; lie à l'adresse ou au nom d'hôte host (par défaut : 127.0.0.1) ; écoute sur le port port (par défaut : 9229) ; attend que le débogueur soit attaché. |
node inspect script.js | Génère un processus enfant pour exécuter le script de l'utilisateur sous l'indicateur --inspect ; et utilise le processus principal pour exécuter le débogueur CLI. |
node inspect --port=xxxx script.js | Génère un processus enfant pour exécuter le script de l'utilisateur sous l'indicateur --inspect ; et utilise le processus principal pour exécuter le débogueur CLI. Écoute sur le port port (par défaut : 9229) |
Activation des scénarios de débogage à distance
Nous recommandons de ne jamais laisser le débogueur écouter sur une adresse IP publique. Si vous devez autoriser des connexions de débogage à distance, nous recommandons l'utilisation de tunnels SSH. Nous fournissons l'exemple suivant à des fins illustratives uniquement. Veuillez comprendre le risque de sécurité lié à l'autorisation d'un accès à distance à un service privilégié avant de continuer.
Supposons que vous exécutiez Node.js sur une machine distante, remote.example.com, que vous souhaitez déboguer. Sur cette machine, vous devez démarrer le processus Node avec l'inspecteur écoutant uniquement localhost (la valeur par défaut).
node --inspect app.jsMaintenant, sur votre machine locale depuis laquelle vous souhaitez initier une connexion client de débogage, vous pouvez configurer un tunnel SSH :
ssh -L 9225:localhost:9229 remote.example.comCela démarre une session de tunnel SSH où une connexion au port 9221 sur votre machine locale sera transférée au port 9229 sur remote.example.com. Vous pouvez maintenant attacher un débogueur tel que Chrome DevTools ou Visual Studio Code à localhost:9221, qui devrait pouvoir déboguer comme si l'application Node.js était exécutée localement.
Débogueur hérité
Le débogueur hérité est obsolète depuis Node.js 7.7.0. Veuillez utiliser --inspect et Inspector à la place.
Lorsqu'il est démarré avec les options --debug ou --debug-brk dans la version 7 et les versions antérieures, Node.js écoute les commandes de débogage définies par le protocole de débogage V8 interrompu sur un port TCP, par défaut 5858. Tout client de débogage qui utilise ce protocole peut se connecter et déboguer le processus en cours ; quelques-uns des plus populaires sont listés ci-dessous.
Le protocole de débogage V8 n'est plus maintenu ni documenté.
Débogueur intégré
Démarrez node debug script_name.js pour démarrer votre script sous le débogueur en ligne de commande intégré. Votre script démarre dans un autre processus Node.js démarré avec l'option --debug-brk, et le processus Node.js initial exécute le script _debugger.js et se connecte à votre cible. Consultez la documentation pour plus d'informations.
node-inspector
Déboguez votre application Node.js avec Chrome DevTools en utilisant un processus intermédiaire qui traduit le protocole Inspector utilisé dans Chromium au protocole de débogueur V8 utilisé dans Node.js. Consultez https://github.com/node-inspector/node-inspector pour plus d'informations.