Отладка Node.js с помощью node inspect и протокола Chrome DevTools

Как применить

Используйте этот метод, когда при отладке Node.js нужен доступ к инспектору: скрытые локальные переменные, зависания асинхронных операций, нестабильные тесты, дочерние процессы, конфликты при запуске, рост потребления памяти или горячие участки кода с высокой нагрузкой на процессор.

Сначала используйте node inspect; обращайтесь к протоколу Chrome DevTools только тогда, когда нужны скриптовые точки останова, автоматический захват состояния, снимки кучи или профили загрузки процессора. Устанавливайте инструменты вне репозитория, если проект уже не зависит от них.

Пауза при входе: node inspect path/to/script.js

TypeScript: node --inspect-brk --import tsx path/to/script.ts

Список целей для инспекции: curl -s http://127.0.0.1:9229/json/list | jq

Путь к OpenClaw CLI: node --inspect-brk openclaw.mjs ...

Путь к тестам OpenClaw: OPENCLAW_VITEST_MAX_WORKERS=1 node --inspect-brk scripts/run-vitest.mjs <file>

Предпочтительно используйте привязки инспектора 127.0.0.1, и не раскрывайте --inspect=0.0.0.0, если сеть изолирована.

В Vitest отлаживайте один файл с одним рабочим процессом и избегайте пулов рабочих процессов во время пошаговой отладки.

Для точек останова в исходном коде TypeScript полезно использовать --enable-source-maps; node inspect всё равно может показывать сгенерированные пути.

Для дочерних процессов NODE_OPTIONS=--inspect-brk может передавать инспектор, но каждому дочернему процессу требуется свой порт.

Для долгоживущих шлюзов или процессов разработки подключайтесь по PID после подтверждения цели с помощью /json/list.

Устанавливайте инструменты вне репозитория, если проект уже не зависит от них.

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

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

Имейте в виду, что --inspect не приостанавливает выполнение; используйте --inspect-brk, когда настройка должна произойти до запуска кода.

Стандартный порт — 9229; для параллельных целей используйте --inspect=0 или уникальный порт.

Если точка останова не срабатывает, проверьте путь к файлу, поведение карты исходного кода и то, не прошло ли выполнение уже мимо этой строки.

Если процесс кажется зависшим после отсоединения, возможно, он всё ещё находится в состоянии паузы в отладчике.