Debug del codice Node.js
Questa guida ti aiuterà ad iniziare a eseguire il debug delle tue app e script Node.js.
Abilitare l'Inspector
Quando avviato con l'opzione --inspect, un processo Node.js ascolta un client di debug. Per impostazione predefinita, ascolterà all'host e alla porta 127.0.0.1:9229. A ogni processo viene inoltre assegnato un UUID univoco.
I client Inspector devono conoscere e specificare l'indirizzo host, la porta e l'UUID per connettersi. Un URL completo sarà simile a ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.
Node.js inizierà anche ad ascoltare i messaggi di debug se riceve un segnale SIGUSR1. (SIGUSR1 non è disponibile su Windows.) In Node.js 7 e precedenti, questo attiva la legacy Debugger API. In Node.js 8 e successivi, attiverà l'API Inspector.
Implicazioni sulla sicurezza
Poiché il debugger ha pieno accesso all'ambiente di esecuzione Node.js, un attore malintenzionato in grado di connettersi a questa porta potrebbe essere in grado di eseguire codice arbitrario per conto del processo Node.js. È importante comprendere le implicazioni sulla sicurezza dell'esposizione della porta del debugger su reti pubbliche e private.
Esporre pubblicamente la porta di debug non è sicuro
Se il debugger è associato a un indirizzo IP pubblico o a 0.0.0.0, qualsiasi client in grado di raggiungere il tuo indirizzo IP sarà in grado di connettersi al debugger senza alcuna restrizione e sarà in grado di eseguire codice arbitrario.
Per impostazione predefinita, node --inspect si lega a 127.0.0.1. È necessario fornire esplicitamente un indirizzo IP pubblico o 0.0.0.0, ecc., se si intende consentire connessioni esterne al debugger. In questo modo potresti esporti a una potenziale minaccia per la sicurezza significativa. Ti suggeriamo di assicurarti che siano in atto firewall e controlli di accesso appropriati per prevenire un'esposizione alla sicurezza.
Vedi la sezione su 'Abilitazione di scenari di debug remoto' per alcuni consigli su come consentire in modo sicuro ai client del debugger remoto di connettersi.
Le applicazioni locali hanno pieno accesso all'inspector
Anche se si lega la porta dell'inspector a 127.0.0.1 (impostazione predefinita), tutte le applicazioni in esecuzione localmente sul tuo computer avranno accesso illimitato. Questo è progettato per consentire ai debugger locali di potersi collegare comodamente.
Browser, WebSocket e politica dell'origine uguale
I siti web aperti in un browser web possono effettuare richieste WebSocket e HTTP in base al modello di sicurezza del browser. È necessaria una connessione HTTP iniziale per ottenere un ID di sessione di debug univoco. La politica dell'origine uguale impedisce ai siti web di stabilire questa connessione HTTP. Per una maggiore sicurezza contro gli attacchi di rebinding DNS, Node.js verifica che le intestazioni "Host" per la connessione specifichino un indirizzo IP o localhost precisamente.
Queste politiche di sicurezza vietano la connessione a un server di debug remoto specificando il nome host. È possibile aggirare questa restrizione specificando l'indirizzo IP o utilizzando tunnel SSH come descritto di seguito.
Client Inspector
Un debugger CLI minimale è disponibile con node inspect myscript.js. Diversi strumenti commerciali e open source possono anche connettersi a Node.js Inspector.
Chrome DevTools 55+, Microsoft Edge
- Opzione 1: Aprire
chrome://inspectin un browser basato su Chromium oedge://inspectin Edge. Fare clic sul pulsante Configura e assicurarsi che l'host e la porta di destinazione siano elencati. - Opzione 2: Copiare
devtoolsFrontendUrldall'output di/json/list(vedi sopra) o dal testo del suggerimento--inspecte incollarlo in Chrome.
Vedi https://github.com/ChromeDevTools/devtools-frontend, https://www.microsoftedgeinsider.com per maggiori informazioni.
Visual Studio Code 1.10+
- Nel pannello Debug, fare clic sull'icona delle impostazioni per aprire
.vscode/launch.json. Selezionare "Node.js" per la configurazione iniziale.
Vedi https://github.com/microsoft/vscode per maggiori informazioni.
JetBrains WebStorm e altri IDE JetBrains
- Creare una nuova configurazione di debug Node.js e premere Debug.
--inspectverrà utilizzato per impostazione predefinita per Node.js 7+. Per disabilitare, deselezionarejs.debugger.node.use.inspectnel Registro di sistema IDE. Per ulteriori informazioni sull'esecuzione e il debug di Node.js in WebStorm e altri IDE JetBrains, consultare la Guida online di WebStorm.
chrome-remote-interface
- Libreria per semplificare le connessioni agli endpoint del Inspector Protocol. Vedi https://github.com/cyrus-and/chrome-remote-interface per maggiori informazioni.
Gitpod
- Avvia una configurazione di debug Node.js dalla vista
Debugo premiF5. Istruzioni dettagliate
Vedi https://www.gitpod.io per maggiori informazioni.
Eclipse IDE con estensione Eclipse Wild Web Developer
- Da un file
.js, scegliDebug As... > Node program, oppure crea una configurazione di debug per collegare il debugger all'applicazione Node.js in esecuzione (già avviata con--inspect).
Vedi https://eclipse.org/eclipseide per maggiori informazioni.
Opzioni della riga di comando
La seguente tabella elenca l'impatto di vari flag di runtime sul debug:
| Flag | Significato |
|---|---|
--inspect | Abilita il debug con Node.js Inspector. Ascolta sull'indirizzo e sulla porta predefiniti (127.0.0.1:9229) |
--inspect-brk | Abilita il debug con Node.js Inspector. Ascolta sull'indirizzo e sulla porta predefiniti (127.0.0.1:9229); Interrompe prima che inizi il codice utente |
--inspect=[host:port] | Abilita l'agente inspector; Lega all'indirizzo o al nome host host (predefinito: 127.0.0.1); Ascolta sulla porta port (predefinito: 9229) |
--inspect-brk=[host:port] | Abilita l'agente inspector; Lega all'indirizzo o al nome host host (predefinito: 127.0.0.1); Ascolta sulla porta port (predefinito: 9229); Interrompe prima che inizi il codice utente |
--inspect-wait | Abilita l'agente inspector; Ascolta sull'indirizzo e sulla porta predefiniti (127.0.0.1:9229); Attende che il debugger venga collegato. |
--inspect-wait=[host:port] | Abilita l'agente inspector; Lega all'indirizzo o al nome host host (predefinito: 127.0.0.1); Ascolta sulla porta port (predefinito: 9229); Attende che il debugger venga collegato. |
node inspect script.js | Genera un processo figlio per eseguire lo script dell'utente con il flag --inspect; e utilizza il processo principale per eseguire il debugger CLI. |
node inspect --port=xxxx script.js | Genera un processo figlio per eseguire lo script dell'utente con il flag --inspect; e utilizza il processo principale per eseguire il debugger CLI. Ascolta sulla porta port (predefinito: 9229) |
Abilitazione di scenari di debug remoto
Si consiglia di non far mai ascoltare il debugger su un indirizzo IP pubblico. Se è necessario consentire connessioni di debug remoto, si consiglia di utilizzare invece tunnel SSH. Forniamo il seguente esempio a solo scopo illustrativo. Prima di procedere, comprendere il rischio per la sicurezza derivante dal consentire l'accesso remoto a un servizio privilegiato.
Supponiamo di eseguire Node.js su una macchina remota, remote.example.com, che si desidera poter eseguire il debug. Su tale macchina, è necessario avviare il processo node con l'inspector in ascolto solo su localhost (impostazione predefinita).
node --inspect app.jsOra, sulla macchina locale da cui si desidera avviare una connessione client di debug, è possibile configurare un tunnel SSH:
ssh -L 9225:localhost:9229 remote.example.comQuesto avvia una sessione di tunnel SSH in cui una connessione alla porta 9221 sulla macchina locale verrà inoltrata alla porta 9229 su remote.example.com. È ora possibile collegare un debugger come Chrome DevTools o Visual Studio Code a localhost:9221, che dovrebbe essere in grado di eseguire il debug come se l'applicazione Node.js fosse in esecuzione localmente.
Debugger legacy
Il debugger legacy è stato deprecato a partire da Node.js 7.7.0. Si prega di utilizzare --inspect e Inspector invece.
Quando avviato con gli switch --debug o --debug-brk nella versione 7 e precedenti, Node.js ascolta i comandi di debug definiti dal protocollo di debug V8 dismesso su una porta TCP, di default 5858. Qualsiasi client di debug che utilizza questo protocollo può connettersi ed eseguire il debug del processo in esecuzione; di seguito sono elencati alcuni dei più popolari.
Il protocollo di debug V8 non è più mantenuto o documentato.
Debugger integrato
Avviare node debug script_name.js per avviare lo script sotto il debugger della riga di comando integrato. Lo script viene avviato in un altro processo Node.js avviato con l'opzione --debug-brk, e il processo Node.js iniziale esegue lo script _debugger.js e si connette al target. Vedere docs per maggiori informazioni.
node-inspector
Esegui il debug della tua app Node.js con Chrome DevTools usando un processo intermedio che traduce il protocollo Inspector Protocol utilizzato in Chromium nel protocollo V8 Debugger utilizzato in Node.js. Vedi https://github.com/node-inspector/node-inspector per maggiori informazioni.