Depurando Node.js
Este guia ajudará você a começar a depurar seus aplicativos e scripts Node.js.
Ativar o Inspetor
Quando iniciado com o interruptor --inspect, um processo Node.js escuta um cliente de depuração. Por padrão, ele escutará no host e na porta 127.0.0.1:9229. Cada processo também recebe um UUID exclusivo.
Os clientes do Inspetor devem conhecer e especificar o endereço do host, a porta e o UUID para conectar. Uma URL completa terá uma aparência semelhante a ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.
O Node.js também começará a escutar mensagens de depuração se receber um sinal SIGUSR1. (SIGUSR1 não está disponível no Windows.) No Node.js 7 e anterior, isso ativa a API de depurador herdada. No Node.js 8 e posterior, ele ativará a API do Inspetor.
Implicações de Segurança
Como o depurador tem acesso total ao ambiente de execução do Node.js, um ator malicioso capaz de se conectar a essa porta pode ser capaz de executar código arbitrário em nome do processo Node.js. É importante entender as implicações de segurança de expor a porta do depurador em redes públicas e privadas.
Expor a porta de depuração publicamente não é seguro
Se o depurador estiver vinculado a um endereço IP público ou a 0.0.0.0, quaisquer clientes que puderem acessar seu endereço IP poderão se conectar ao depurador sem nenhuma restrição e poderão executar código arbitrário.
Por padrão, node --inspect vincula a 127.0.0.1. Você precisa fornecer explicitamente um endereço IP público ou 0.0.0.0, etc., se pretende permitir conexões externas ao depurador. Fazer isso pode expô-lo a uma ameaça de segurança potencialmente significativa. Sugerimos que você garanta que haja firewalls e controles de acesso apropriados para evitar uma exposição de segurança.
Consulte a seção sobre 'Habilitando cenários de depuração remota' para obter algumas dicas sobre como permitir com segurança que clientes de depurador remotos se conectem.
Aplicativos locais têm acesso total ao inspetor
Mesmo que você vincule a porta do inspetor a 127.0.0.1 (o padrão), quaisquer aplicativos em execução localmente em sua máquina terão acesso irrestrito. Isso é por design para permitir que depuradores locais se conectem convenientemente.
Navegadores, WebSockets e política de mesma origem
Sites abertos em um navegador web podem fazer solicitações WebSocket e HTTP sob o modelo de segurança do navegador. Uma conexão HTTP inicial é necessária para obter um ID de sessão de depurador exclusivo. A política de mesma origem impede que os sites consigam fazer essa conexão HTTP. Para segurança adicional contra ataques de religação DNS, o Node.js verifica se os cabeçalhos 'Host' para a conexão especificam um endereço IP ou localhost precisamente.
Essas políticas de segurança impedem a conexão a um servidor de depuração remoto especificando o nome de host. Você pode contornar essa restrição especificando o endereço IP ou usando túneis SSH, conforme descrito abaixo.
Clientes do Inspetor
Um depurador CLI mínimo está disponível com node inspect myscript.js. Várias ferramentas comerciais e de código aberto também podem se conectar ao Node.js Inspector.
Chrome DevTools 55+, Microsoft Edge
- Opção 1: Abra
chrome://inspectem um navegador baseado em Chromium ouedge://inspectno Edge. Clique no botão Configurar e verifique se o host e a porta de destino estão listados. - Opção 2: Copie o
devtoolsFrontendUrlda saída de/json/list(veja acima) ou o texto de dica--inspecte cole no Chrome.
Veja https://github.com/ChromeDevTools/devtools-frontend, https://www.microsoftedgeinsider.com para mais informações.
Visual Studio Code 1.10+
- No painel Depurar, clique no ícone de configurações para abrir
.vscode/launch.json. Selecione "Node.js" para a configuração inicial.
Veja https://github.com/microsoft/vscode para mais informações.
JetBrains WebStorm e outros IDEs JetBrains
- Crie uma nova configuração de depuração Node.js e clique em Depurar.
--inspectserá usado por padrão para Node.js 7+. Para desabilitar, desmarquejs.debugger.node.use.inspectno Registro do IDE. Para saber mais sobre execução e depuração de Node.js no WebStorm e outros IDEs JetBrains, consulte a Ajuda online do WebStorm.
chrome-remote-interface
- Biblioteca para facilitar conexões com endpoints do Inspector Protocol. Veja https://github.com/cyrus-and/chrome-remote-interface para mais informações.
Gitpod
- Inicie uma configuração de depuração Node.js na visualização "Depurar" ou pressione
F5. Instruções detalhadas
Veja https://www.gitpod.io para mais informações.
Eclipse IDE com extensão Eclipse Wild Web Developer
- A partir de um arquivo
.js, escolhaDepurar como... > Programa Node, ou crie uma Configuração de Depuração para anexar o depurador ao aplicativo Node.js em execução (já iniciado com--inspect).
Veja https://eclipse.org/eclipseide para mais informações.
Opções de linha de comando
A tabela a seguir lista o impacto de várias flags de tempo de execução na depuração:
| Flag | Significado |
|---|---|
--inspect | Ativa a depuração com o Node.js Inspector. Escuta no endereço e porta padrão (127.0.0.1:9229) |
--inspect-brk | Ativa a depuração com o Node.js Inspector. Escuta no endereço e porta padrão (127.0.0.1:9229); Interrompe antes do início do código do usuário |
--inspect=[host:port] | Ativa o agente inspetor; Vincula ao endereço ou nome de host host (padrão: 127.0.0.1); Escuta na porta port (padrão: 9229) |
--inspect-brk=[host:port] | Ativa o agente inspetor; Vincula ao endereço ou nome de host host (padrão: 127.0.0.1); Escuta na porta port (padrão: 9229); Interrompe antes do início do código do usuário |
--inspect-wait | Ativa o agente inspetor; Escuta no endereço e porta padrão (127.0.0.1:9229); Aguarda a anexação do depurador. |
--inspect-wait=[host:port] | Ativa o agente inspetor; Vincula ao endereço ou nome de host host (padrão: 127.0.0.1); Escuta na porta port (padrão: 9229); Aguarda a anexação do depurador. |
node inspect script.js | Gera processo filho para executar o script do usuário sob a flag --inspect; e usa o processo principal para executar o depurador CLI. |
node inspect --port=xxxx script.js | Gera processo filho para executar o script do usuário sob a flag --inspect; e usa o processo principal para executar o depurador CLI. Escuta na porta port (padrão: 9229) |
Habilitando cenários de depuração remota
Recomendamos que você nunca deixe o depurador escutar em um endereço IP público. Se precisar permitir conexões de depuração remotas, recomendamos o uso de túneis SSH. Fornecemos o exemplo a seguir apenas para fins ilustrativos. Por favor, entenda o risco de segurança de permitir acesso remoto a um serviço privilegiado antes de prosseguir.
Digamos que você esteja executando Node.js em uma máquina remota, remote.example.com, que você deseja depurar. Nessa máquina, você deve iniciar o processo node com o inspetor escutando apenas em localhost (o padrão).
node --inspect app.jsAgora, em sua máquina local, de onde você deseja iniciar uma conexão do cliente de depuração, você pode configurar um túnel SSH:
ssh -L 9225:localhost:9229 remote.example.comIsso inicia uma sessão de túnel SSH onde uma conexão para a porta 9221 em sua máquina local será encaminhada para a porta 9229 em remote.example.com. Agora você pode conectar um depurador como Chrome DevTools ou Visual Studio Code a localhost:9221, que deve ser capaz de depurar como se o aplicativo Node.js estivesse sendo executado localmente.
Depurador Legado
O depurador legado foi depreciado a partir do Node.js 7.7.0. Por favor, use --inspect e Inspector.
Quando iniciado com as opções --debug ou --debug-brk na versão 7 e anteriores, o Node.js escuta comandos de depuração definidos pelo Protocolo de Depuração V8 descontinuado em uma porta TCP, por padrão 5858. Qualquer cliente de depurador que fale este protocolo pode se conectar e depurar o processo em execução; alguns populares são listados abaixo.
O Protocolo de Depuração V8 não é mais mantido ou documentado.
Depurador embutido
Inicie node debug script_name.js para iniciar seu script sob o depurador de linha de comando embutido. Seu script inicia em outro processo Node.js iniciado com a opção --debug-brk, e o processo Node.js inicial executa o script _debugger.js e se conecta ao seu destino. Veja docs para mais informações.
node-inspector
Depure seu aplicativo Node.js com o Chrome DevTools usando um processo intermediário que traduz o Protocolo do Inspetor usado no Chromium para o protocolo do depurador V8 usado no Node.js. Veja https://github.com/node-inspector/node-inspector para mais informações.