Conceptos básicos de depuración

8 ejemplos para empezar a depurar backends de Node.js: 6 básicos y 2 intermedios.

Requisitos previos

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

node --version   # v24.18.0

Ejemplos básicos

1. Iniciar el Inspector al arrancar

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

• Abre chrome://inspect -> Configurar -> añade localhost:9229 -> inspeccionar
• Puerto predeterminado 9229; usa --inspect=9230 si está ocupado
• Vincula 0.0.0.0 solo en redes de desarrollo de confianza: --inspect=0.0.0.0

Relacionado: Búsqueda de fugas de memoria - instantáneas de montón en DevTools

2. Interrumpir en la primera línea

node --inspect-brk src/main.ts

• El proceso se pausa antes de que se ejecute el código de usuario; adjunta el depurador y luego reanuda
• Útil cuando el error ocurre en el momento de la carga del módulo
• CI no debe usar --inspect-brk sin tiempo de espera

3. Declaración debugger

export function charge(amountCents: number) {
  if (amountCents < 0) {
    debugger; // la ejecución se pausa cuando el inspector está adjunto
    throw new Error("invalid amount");
  }
  return { charged: amountCents };
}

• Elimina debugger antes de la fusión - ESLint no-debugger en CI
• Funciona con tsx cuando el inspector está habilitado
• Prefiere los puntos de interrupción en DevTools para rutas de código compartidas

4. NODE_OPTIONS en scripts npm

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

• Windows: usa cross-env NODE_OPTIONS=--inspect
• tsx watch reinicia el proceso: vuelve a adjuntar DevTools después de la recarga
• Combínalo con VS Code launch.json para el estándar del equipo

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 correlación segura en producción con requestId
• Depurador para avanzar paso a paso cuando el estado no está claro
• util.inspect imprime objetos anidados legibles en la terminal

Relacionado: Conceptos básicos de registro - registros estructurados en producción

6. Imprimir la traza de la pila

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

• Error.captureStackTrace personaliza la pila en el código de la biblioteca
• Registra las pilas solo en el lado del servidor; nunca las devuelvas a los clientes de la API en producción

Ejemplos intermedios

7. Mapas de origen con TypeScript

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

• DevTools muestra líneas .ts, no .js transpiladas
• Salida de tsc + node --inspect dist/main.js para depuración similar a producción
• tsx maneja TS directamente sin un paso de compilación separado

8. Adjuntar a un proceso en ejecución

# Encontrar PID
pgrep -fl "node dist/main"
 
# Adjuntar el inspector a un proceso en vivo (pausa breve)
kill -USR1 <pid>
# Luego node registra: Debugger listening...

• SIGUSR1 habilita la inspección en un Node en ejecución (si no se inició con --inspect)
• Úsalo solo en staging; adjuntar en producción requiere la aprobación del runbook
• Combínalo con la creación de perfiles de Incidente de bloqueo del bucle de eventos

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.