Guia completo para debugar JavaScript de forma eficiente

Debugar JavaScript é uma habilidade que separa quem apenas escreve código de quem realmente entende o que o código faz. Não se trata de achar o erro, mas de entender o fluxo de dados e as decisões que o programa toma a cada linha. Quando dominamos as ferramentas certas, o processo deixa de ser tentativa e erro e vira investigação estruturada.

Neste guia, vamos percorrer as técnicas mais eficientes para debugar JavaScript, desde o console do navegador até breakpoints avançados no DevTools. O resultado esperado é que você saia daqui capaz de identificar e corrigir bugs comuns em minutos, não em horas. Pré-requisitos: conhecimento básico de JavaScript e um navegador moderno (Chrome ou Firefox).

Passo 1: Comece pelo console, mas com estratégia

O console.log é a ferramenta mais básica e a mais usada. O problema é que muita gente joga console.log em tudo e depois não sabe onde procurar. A chave é usar o console com intenção: pergunte-se qual informação você precisa para confirmar ou descartar uma hipótese.

Em vez de console.log(variable), use console.log({ variable }) para ver o nome e o valor juntos. Para objetos, console.table(array) exibe os dados em formato de tabela, muito mais legível. E para rastrear chamadas de função, console.trace() mostra a pilha de execução até aquele ponto.

Dica prática: quando estiver debugando um loop, não coloque console.log dentro dele, isso polui o console e desacelera a página. Use um breakpoint condicional (veremos no Passo 3).

Erro comum: esquecer de remover console.log do código de produção. Ferramentas como ESLint podem alertar sobre isso, e bundlers como Webpack permitem remover logs automaticamente em build de produção.

Passo 2: Use a palavra-chave debugger; como pausa estratégica

Inserir debugger; no código é como colocar uma placa de "pare" no meio do fluxo. Quando o navegador encontra essa instrução com o DevTools aberto, a execução pausa automaticamente naquela linha. Você pode inspecionar variáveis, ver a pilha de chamadas e avançar passo a passo.

A vantagem sobre console.log é que você não precisa adivinhar o que imprimir: vê tudo que está no escopo naquele momento. Depois de corrigir o bug, é só remover a linha debugger;.

Dica prática: coloque debugger; dentro de um condicional para pausar apenas em situações específicas: if (user.id === 42) { debugger; }. Isso evita pausar em cada iteração de um loop de mil itens.

Erro comum: deixar debugger; no código e enviar para produção. Embora o navegador só pause com DevTools aberto, o código fica poluído e pode causar confusão em revisão. Sempre revise commits que contenham essa instrução.

Passo 3: Domine os breakpoints no DevTools

O painel Sources do Chrome DevTools (ou Debugger no Firefox) é onde o debug realmente ganha potência. Você pode clicar no número da linha para adicionar um breakpoint simples. Quando a execução chegar ali, tudo pausa.

Mas o poder está nos breakpoints especiais:

• Breakpoint condicional: clique com o botão direito no número da linha e escolha "Add conditional breakpoint". Digite uma expressão como count > 10. O código só pausa quando a condição for verdadeira. Perfeito para loops.
• Breakpoint de evento: no painel Event Listener Breakpoints, você pode pausar em qualquer evento do DOM (click, keydown, scroll). Útil para entender por que um clique não está funcionando.
• Breakpoint de XHR/fetch: na aba XHR/Fetch Breakpoints, pausa quando uma requisição para uma URL específica é feita. Ajuda a debugar chamadas de API.
• Breakpoint de linha de log: em vez de pausar, você pode configurar para logar um valor automaticamente sem parar a execução. Clique com botão direito e escolha "Add log point". É um console.log sem sujar o código.

Dica prática: use breakpoints de log para monitorar valores que mudam com frequência sem interromper o fluxo. É mais rápido que adicionar console.log e depois removê-los.

Erro comum: colocar breakpoint em linha de declaração de variável (let x = 5). Nesse ponto, a variável ainda não foi inicializada. Coloque o breakpoint na linha seguinte para ver o valor real.

Passo 4: Inspecione o escopo e a pilha de chamadas

Quando a execução pausa em um breakpoint, o painel direito do DevTools mostra três seções fundamentais:

• Scope (Escopo): lista todas as variáveis disponíveis no contexto atual, incluindo Local (função atual), Closure (funções externas) e Global. Você pode ver valores e até editá-los clicando duas vezes.
• Call Stack (Pilha de Chamadas): mostra a sequência de funções que levaram até aquele ponto. Se um erro acontece dentro de uma função chamada por outra, você vê o caminho completo. Isso é essencial para entender a origem do problema.
• Watch (Observação): você pode adicionar expressões que quer monitorar continuamente, como user.name ou items.length. Elas são recalculadas a cada pausa.

Dica prática: se o valor de uma variável não faz sentido, clique com botão direito nela e selecione "Store as global variable". O DevTools cria uma referência temporária (temp1, temp2) que você pode usar no console para testar funções ou transformações.

Erro comum: ignorar a pilha de chamadas. Muitas vezes o erro não está na função atual, mas em quem a chamou. A pilha mostra exatamente isso.

Passo 5: Use breakpoints de requisição de rede para debugar APIs

Erros de integração com APIs são frequentes. Em vez de adivinhar o que foi enviado, vá até a aba Network do DevTools, clique com botão direito em uma requisição e selecione "Break on" > "XHR/fetch breakpoints". Você pode configurar para pausar antes da requisição ser enviada ou quando a resposta chegar.

Isso permite inspecionar o payload enviado e a resposta recebida antes que o código tente processá-los. Muitas vezes o problema está em um campo faltando no JSON ou em um status HTTP inesperado.

Dica prática: para APIs que retornam erros 4xx/5xx, configure um breakpoint de resposta com status code >= 400. Assim você pausa apenas quando algo der errado.

Erro comum: debugar apenas o front-end e esquecer de verificar o que o servidor realmente enviou. Sempre confirme o payload no Network antes de culpar o JavaScript.

Passo 6: Depure código assíncrono com cuidado

Promises, async/await e callbacks assíncronos são especialmente traiçoeiros porque o fluxo não é linear. O DevTools tem recursos específicos:

• Em breakpoints, marque a opção "Async" no painel Call Stack para ver a cadeia de Promises que levou ao ponto atual.
• Use console.log com timestamps: console.log('início', Date.now()) e console.log('fim', Date.now()) para medir quanto tempo cada etapa leva.
• Para debugar Promises, coloque debugger; dentro de .then() ou catch(). Lembre-se de que o código assíncrono executa em um ciclo de eventos diferente.

Dica prática: se uma Promise está sendo rejeitada e você não vê o erro, adicione um catch global: window.addEventListener('unhandledrejection', event => { debugger; }). Isso pausa em qualquer Promise rejeitada sem tratamento.

Erro comum: assumir que o código assíncrono executa em ordem de escrita. Sempre verifique a pilha de chamadas para confirmar a sequência real.

Passo 7: Depure Node.js com o mesmo mindset

Node.js também pode ser debugado com breakpoints. Use node --inspect seu_arquivo.js e abra chrome://inspect no navegador. Você verá seu código Node.js no DevTools, com todos os recursos que já vimos: breakpoints, escopo, pilha de chamadas.

Para um debug mais leve, o node inspect (sem o --inspect) oferece um debugger no terminal, com comandos como c (continue), n (next) e repl (para avaliar expressões).

Dica prática: em projetos grandes, configure o launch.json do VS Code para debugar Node.js diretamente do editor. Assim você não precisa alternar entre terminais.

Erro comum: tentar debugar Node.js apenas com console.log. O debugger interativo é muito mais rápido para entender fluxos complexos, especialmente com callbacks aninhados.

Checklist rápido: o que você aprendeu

• Usar console.log, console.table e console.trace com intenção.
• Inserir debugger; como pausa estratégica.
• Configurar breakpoints simples, condicionais e de log no DevTools.
• Inspecionar escopo, pilha de chamadas e watch expressions.
• Debugar requisições de rede com breakpoints de XHR.
• Tratar código assíncrono com ferramentas específicas.
• Aplicar as mesmas técnicas para Node.js.

Agora, da próxima vez que um bug aparecer, você tem um roteiro. Comece com uma hipótese, aplique a técnica certa e confirme com os dados que o debugger oferece. Debugar vira investigação, não adivinhação.

Perguntas frequentes sobre debug de JavaScript

Como debugar JavaScript no Chrome?

Abra o DevTools (F12), vá na aba Sources, encontre seu arquivo JS e clique no número da linha para adicionar um breakpoint. Recarregue a página ou dispare a ação que executa o código. A execução pausará no breakpoint.

Qual a diferença entre console.log e debugger;?

console.log apenas imprime valores no console, sem pausar. debugger; pausa a execução e permite inspecionar variáveis, pilha de chamadas e o estado completo naquele instante. Use console.log para valores simples e debugger; para fluxos complexos.

Como debugar código assíncrono com Promises?

Coloque debugger; dentro do .then() ou catch(). No DevTools, ative a opção "Async" no painel Call Stack para ver a cadeia de Promises. Para Promises rejeitadas sem tratamento, use o evento unhandledrejection no window.

Como remover console.log do código de produção?

Configure seu bundler (Webpack, Vite) para remover logs em build de produção. Use plugins como terser-webpack-plugin com a opção drop_console: true ou configure ESLint com a regra no-console para alertar.

O que é breakpoint condicional e quando usar?

É um breakpoint que só pausa quando uma condição que você define é verdadeira. Use dentro de loops (ex: pausar apenas quando i === 50) ou em funções chamadas muitas vezes (ex: pausar apenas quando user.role === 'admin').

Como debugar Node.js sem o navegador?

Use node inspect seu_arquivo.js para um debugger no terminal. Comandos: c (continue), n (next), s (step into), repl (avaliar expressões). Para interface visual, use node --inspect e abra chrome://inspect no navegador.