Node-Inspect-Debugger

Node Inspect Debugger

Verwenden für Node.js-Debugging, das Inspector-Zugriff benötigt: versteckte lokale Variablen, asynchrone Hänger, flaky Tests, Child-Prozesse, Start-Race-Conditions, Speicherwachstum oder CPU-hot-paths.

Standardmäßig node inspect verwenden. Chrome DevTools Protocol nur dann verwenden, wenn programmatische Haltepunkte, automatisierte Zustandserfassung, Heap-Snapshots oder CPU-Profile benötigt werden.

Schnellstart

• Beim Einstieg pausieren: node inspect path/to/script.js
• TypeScript: node --inspect-brk --import tsx path/to/script.ts
• Vorhandene PID: kill -SIGUSR1 <pid> dann node inspect -p <pid>
• Inspect-Ziele auflisten: curl -s http://127.0.0.1:9229/json/list | jq
• OpenClaw CLI-Pfad: node --inspect-brk openclaw.mjs ...
• OpenClaw Test-Pfad: OPENCLAW_VITEST_MAX_WORKERS=1 node --inspect-brk scripts/run-vitest.mjs <file>

Debugger-REPL

• Fortsetzen/Schritt: cont, next, step, out, pause
• Haltepunkte: sb('file.js', 42), sb(42), sb('functionName'), breakpoints, cb('file.js', 42)
• Untersuchen: bt, list(8), watch('expr'), exec expr
• Aktueller Gültigkeitsbereich: repl, dann lokale Variablen direkt auswerten; Strg+C verlässt den REPL-Modus.
• Sicheres Beenden: cont vor dem Verlassen, wenn der Prozess fortgesetzt werden soll; andernfalls kill.

OpenClaw-Tipps

• Bevorzugt 127.0.0.1 Inspector-Bindungen verwenden. --inspect=0.0.0.0 nur freigeben, wenn das Netzwerk isoliert ist.
• Für Vitest eine Datei mit einem Worker debuggen. Vermeiden Sie Worker-Pools während des Schrittdurchlaufs.
• Für TS-Quellhaltepunkte --enable-source-maps verwenden, wenn nützlich; node inspect kann weiterhin emittierte Pfade anzeigen.
• Für Child-Prozesse kann NODE_OPTIONS=--inspect-brk den Inspector weitergeben, aber jeder Child-Prozess benötigt einen eigenen Port.
• Für langlebige Gateway- oder Entwicklungsumgebungsprozesse per PID anhängen, nachdem das Ziel mit /json/list bestätigt wurde.

Programmatische CDP

Werkzeuge außerhalb des Repositorys installieren, sofern das Projekt nicht bereits darauf angewiesen ist:

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

Minimaler Treiber:

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();
})();

Profile

• CPU: Profiler aktivieren, start, warten, stop, /tmp/profile.cpuprofile schreiben, in Chrome DevTools öffnen.
• Heap: HeapProfiler aktivieren, addHeapSnapshotChunk sammeln, takeHeapSnapshot aufrufen, /tmp/heap.heapsnapshot schreiben.

Fallstricke

• --inspect pausiert nicht; verwenden Sie --inspect-brk, wenn die Einrichtung vor der Codeausführung erfolgen muss.
• Standardport ist 9229; verwenden Sie --inspect=0 oder einen eindeutigen Port für parallele Ziele.
• Wenn ein Haltepunkt nicht zuschlägt, überprüfen Sie den Dateipfad, das Verhalten der Quellkarten und ob die Ausführung die Zeile bereits passiert hat.
• Wenn der Prozess nach dem Trennen eingefroren erscheint, könnte er noch im Debugger pausieren.