Como debugar Node.js: guia passo a passo prático

Se você já passou horas tentando entender por que uma variável está undefined ou uma requisição HTTP retorna 500, sabe que debugar é parte inevitável do desenvolvimento Node.js. Este guia cobre o essencial: do método mais básico (e limitado) até o depurador profissional do VS Code, com dicas para evitar os erros mais comuns. Ao final, você terá um fluxo de debug que economiza tempo e cabeça.

Pré-requisitos

• Node.js instalado (versão 12 ou superior, de preferência LTS)
• VS Code instalado (qualquer versão recente)
• Um projeto Node.js simples para testar (pode ser um arquivo .js com uma função que retorna algo)

Passo 1: Comece com o console.log (mas não pare por aí)

O jeito mais rápido de debugar é espalhar console.log pelo código. Você imprime o valor de uma variável em um ponto específico e vê no terminal se ela corresponde ao esperado.

function soma(a, b) { console.log('a:', a, 'b:', b); return a + b; }

console.log(soma(2, 3)); // a: 2 b: 3 → 5

Erro comum a evitar: esquecer de remover os logs após o debug. Eles poluem o terminal e, em produção, podem vazar dados sensíveis. Em vez de console.log, use console.debug, muitos linters alertam sobre console.log em commits.

Passo 2: Use o depurador embutido do Node.js (sem IDE)

O Node.js vem com um depurador nativo. Execute seu arquivo com a flag --inspect:

node --inspect seu-arquivo.js

Isso inicia um servidor WebSocket na porta 9230 (padrão). Você pode abrir chrome://inspect no Chrome e clicar em "Open dedicated DevTools for Node". Lá, adicione breakpoints na aba Sources e veja o stack trace, variáveis locais e escopo.

Dica: Para pausar na primeira linha do código, use --inspect-brk em vez de --inspect. O script só começa após você clicar em "Play" no DevTools.

Passo 3: Configure o depurador do VS Code (recomendado)

O VS Code tem integração nativa com o depurador Node.js. Para configurar:

1. Abra seu projeto no VS Code.
2. Clique no ícone de "Run and Debug" (Ctrl+Shift+D).
3. Clique em "create a launch.json file" e selecione "Node.js".

O VS Code gera um arquivo .vscode/launch.json parecido com este:

{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Launch Program", "skipFiles": ["<node_internals>/**"], "program": "${workspaceFolder}/seu-arquivo.js" } ] }

Ajuste o campo program para o arquivo que você quer depurar.

Erro comum a evitar: não definir o caminho correto do arquivo. O VS Code usa o workspace como raiz. Se seu arquivo está em src/index.js, coloque "${workspaceFolder}/src/index.js".

Passo 4: Adicione breakpoints e inspecione variáveis

Com o depurador configurado:

• Clique à esquerda do número da linha onde quer pausar (um círculo vermelho aparece).
• Pressione F5 para iniciar.
• O código pausa no breakpoint. Você vê:
• Variáveis (Locals, Globals, Closure)
• Watch (adicione expressões como a + b)
• Call Stack (a pilha de chamadas)
• Passo a passo: F10 (pular linha), F11 (entrar em função), Shift+F11 (sair da função)

Dica: Use o painel Watch para expressões mais complexas, como array.length ou obj.prop?.value. Isso evita ter que adicionar múltiplos breakpoints.

Passo 5: Depure com logs estruturados (alternativa avançada)

Para cenários onde breakpoints são inviáveis (ex: servidores em produção), use o módulo debug do npm. Instale com npm install debug e use:

const debug = require('debug')('app:minha-funcao');

function minhaFuncao(param) { debug('param recebido: %o', param); // ... }

Execute com a variável de ambiente DEBUG=app:* para ver logs filtrados:

DEBUG=app:* node seu-arquivo.js

Erro comum a evitar: não nomear namespaces de forma consistente. Use app:modulo:submodulo para facilitar o filtro. E lembre: em produção, nunca ative DEBUG=*, isso loga tudo e derruba performance.

Passo 6: Depure erros assíncronos com stack traces limpos

Promises rejeitadas sem .catch() geram mensagens de erro pouco informativas. Ative o hook process.on('unhandledRejection'):

process.on('unhandledRejection', (reason, promise) => { console.error('Promise rejeitada não tratada:', reason); });

No Node.js 15+, você pode usar --unhandled-rejections=strict para transformar rejeições não tratadas em exceções:

node --unhandled-rejections=strict seu-arquivo.js

Dica: Em async/await, use try/catch em volta de chamadas que podem lançar erro. O depurador do VS Code pausa em exceções não capturadas se você marcar a opção "Uncaught Exceptions" no painel de breakpoints.

Checklist rápido

• [ ] Testei com console.log e removi antes do commit?
• [ ] Configurei o launch.json no VS Code?
• [ ] Adicionei breakpoints nas linhas críticas?
• [ ] Usei Watch para expressões complexas?
• [ ] Ativei o tratamento de unhandledRejection?
• [ ] Em produção, uso logs estruturados com o módulo debug?

Perguntas frequentes sobre debug em Node.js

Qual a diferença entre --inspect e --inspect-brk?

--inspect inicia o depurador mas executa o script imediatamente. --inspect-brk pausa na primeira linha, esperando você conectar o DevTools ou IDE. Use --inspect-brk quando precisar depurar desde o início da execução.

Como debugar um servidor Express em execução?

Adicione --inspect ao comando de inicialização (ex: node --inspect server.js). Conecte pelo Chrome DevTools ou VS Code. Você pode adicionar breakpoints nos middlewares e rotas normalmente.

O depurador do VS Code funciona com TypeScript?

Sim, desde que você tenha o source map ativado no tsconfig.json ("sourceMap": true). Configure o launch.json para apontar para o arquivo .ts e o VS Code faz a tradução automática.

Como depurar código em contêiner Docker?

Exponha a porta do depurador (9230) no docker-compose.yml e use --inspect=0.0.0.0:9230 no comando do contêiner. Conecte pelo VS Code com uma configuração "request": "attach" apontando para localhost:9230.

O que fazer quando o breakpoint não é atingido?

Verifique se o arquivo que você está editando é o mesmo que está sendo executado. No VS Code, confirme que o caminho no launch.json corresponde ao arquivo real. Se usar TypeScript, certifique-se de que o source map está gerando corretamente.

Como debugar testes unitários com Jest?

Use node --inspect-brk node_modules/.bin/jest --runInBand e conecte pelo VS Code. Ou configure um launch.json com "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/jest" e "args": ["--runInBand"].