Noções Básicas de Depuração

8 exemplos para você começar a depurar backends Node.js - 6 básicos e 2 intermediários.

Pré-requisitos

Node.js 24.18.0 instalado localmente. Navegador Chrome ou Edge para DevTools.

node --version   # v24.18.0

Exemplos Básicos

1. Iniciar Inspetor na Inicialização

node --inspect src/main.ts
# Debugger listening on ws://127.0.0.1:9229

• Abra chrome://inspect -> Configure -> adicione localhost:9229 -> inspect
• Porta padrão 9229; use --inspect=9230 se estiver ocupada
• Vincule 0.0.0.0 apenas em redes de desenvolvimento confiáveis: --inspect=0.0.0.0

Relacionado: Caça a Vazamento de Memória - snapshots de heap no DevTools

2. Parar na Primeira Linha

node --inspect-brk src/main.ts

• O processo pausa antes que o código do usuário seja executado - anexe o depurador e depois retome
• Útil quando o bug ocorre no momento do carregamento do módulo
• CI não deve usar --inspect-brk sem timeout

3. Declaração debugger

export function charge(amountCents: number) {
  if (amountCents < 0) {
    debugger; // a execução pausa quando o inspetor está anexado
    throw new Error("invalid amount");
  }
  return { charged: amountCents };
}

• Remova debugger antes de mesclar - ESLint no-debugger em CI
• Funciona com tsx quando o inspetor está habilitado
• Prefira breakpoints no DevTools para caminhos de código compartilhados

4. NODE_OPTIONS em Scripts npm

{
  "scripts": {
    "dev:debug": "NODE_OPTIONS='--inspect' tsx watch src/main.ts"
  }
}

• Windows: use cross-env NODE_OPTIONS=--inspect
• tsx watch reinicia o processo - reanexe o DevTools após a recarga
• Emparelhe com launch.json do VS Code para um padrão da equipe

5. Log vs Depurador

import { inspect } from "node:util";
 
console.log(inspect({ orderId: "ord_1", meta: { retry: 2 } }, { depth: 5, colors: true }));

• console.log para correlação segura em produção com requestId
• Depurador para percorrer quando o estado não está claro
• util.inspect imprime objetos aninhados legíveis no terminal

Relacionado: Noções Básicas de Logging - logs estruturados em produção

6. Imprimir Rastreamento de Pilha

function fail() {
  throw new Error("payment provider timeout");
}
 
try {
  fail();
} catch (err) {
  console.error(err instanceof Error ? err.stack : err);
}

• Error.captureStackTrace personaliza a pilha em código de biblioteca
• Registre pilhas apenas no lado do servidor - nunca retorne para clientes de API em produção

Exemplos Intermediários

7. Source Maps com TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}

• DevTools mostra linhas .ts, não .js transpilado
• Saída tsc + node --inspect dist/main.js para depuração semelhante à produção
• tsx lida com TS diretamente sem etapa de compilação separada

8. Anexar a Processo em Execução

# Encontrar PID
pgrep -fl "node dist/main"
 
# Anexar inspetor ao processo ativo (pausa breve)
kill -USR1 <pid>
# Então o Node registra: Debugger listening...

• SIGUSR1 habilita o inspetor em um Node em execução (se não foi iniciado com --inspect)
• Use apenas em staging - anexar em produção requer aprovação do runbook
• Combine com perfilamento de Incidente de Travamento do Event-Loop

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.