depurador-node-inspect

Depurador Node Inspect

Use para depuração Node.js que precise de acesso ao inspetor: variáveis locais ocultas, hangs assíncronos, testes intermitentes, processos filhos, corridas de inicialização, crescimento de memória ou gargalos de CPU.

Padrão é usar node inspect primeiro. Use o Protocolo Chrome DevTools apenas quando precisar de breakpoints programáticos, captura automatizada de estado, snapshots de heap ou perfis de CPU.

Início rápido

• Pausar na entrada: node inspect path/to/script.js
• TypeScript: node --inspect-brk --import tsx path/to/script.ts
• PID existente: kill -SIGUSR1 <pid> depois node inspect -p <pid>
• Listar alvos do inspetor: curl -s http://127.0.0.1:9229/json/list | jq
• Caminho CLI do OpenClaw: node --inspect-brk openclaw.mjs ...
• Caminho de teste do OpenClaw: OPENCLAW_VITEST_MAX_WORKERS=1 node --inspect-brk scripts/run-vitest.mjs <file>

REPL do Depurador

• Continuar/passos: cont, next, step, out, pause
• Breakpoints: sb('file.js', 42), sb(42), sb('functionName'), breakpoints, cb('file.js', 42)
• Inspecionar: bt, list(8), watch('expr'), exec expr
• Escopo atual: repl, depois avalie variáveis locais diretamente; Ctrl+C sai do modo repl.
• Sair com segurança: cont antes de sair se o processo deve continuar; caso contrário kill.

Dicas do OpenClaw

• Prefira binds do inspetor em 127.0.0.1. Não exponha --inspect=0.0.0.0 a menos que a rede seja isolada.
• Para Vitest, depure um arquivo com um worker. Evite pools de workers durante a execução passo a passo.
• Para breakpoints em código-fonte TypeScript, use --enable-source-maps quando útil; node inspect ainda pode mostrar caminhos emitidos.
• Para processos filhos, NODE_OPTIONS=--inspect-brk pode propagar o inspetor, mas cada filho precisa de sua própria porta.
• Para processos de gateway ou desenvolvimento de longa duração, anexe por PID após confirmar o alvo com /json/list.

CDP Programático

Instale as ferramentas fora do repositório, a menos que o projeto já dependa delas:

mkdir -p /tmp/cdp-tools
npm --prefix /tmp/cdp-tools i chrome-remote-interface
NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.cjs

Driver mínimo:

const CDP = require("chrome-remote-interface");

(async () => {
  const client = await CDP({ port: 9229 });
  const { Debugger, Runtime } = client;

  Debugger.paused(async ({ callFrames, reason }) => {
    const top = callFrames[0];
    console.log("paused", reason, top.url, top.location.lineNumber + 1);
    const { result } = await Debugger.evaluateOnCallFrame({
      callFrameId: top.callFrameId,
      expression: "JSON.stringify({ pid: process.pid })",
    });
    console.log(result.value ?? result.description);
    await Debugger.resume();
  });

  await Runtime.enable();
  await Debugger.enable();
  await Debugger.setBreakpointByUrl({ urlRegex: ".*target\\.js$", lineNumber: 41 });
  await Runtime.runIfWaitingForDebugger();
})();

Perfis

• CPU: habilite Profiler, start, aguarde, stop, escreva /tmp/profile.cpuprofile, abra no Chrome DevTools.
• Heap: habilite HeapProfiler, colete addHeapSnapshotChunk, chame takeHeapSnapshot, escreva /tmp/heap.heapsnapshot.

Armadilhas

• --inspect não pausa; use --inspect-brk quando a configuração deve acontecer antes do código ser executado.
• A porta padrão é 9229; use --inspect=0 ou uma porta única para alvos paralelos.
• Se um breakpoint falhar, confira o caminho do arquivo, o comportamento do source map e se a execução já passou da linha.
• Se o processo parecer congelado após desconectar, ele pode ainda estar pausado no depurador.