Отладка Node через --inspect и DevTools

—inspect поднимает WebSocket, к которому цепляется отладчик

node --inspect app.js не запускает отладчик — он поднимает сервер. Node включает агент V8 Inspector, который открывает WebSocket и печатает строку вроде Debugger listening on ws://127.0.0.1:9229/<uuid>. По умолчанию он биндится на 127.0.0.1:9229 — только localhost, один общеизвестный порт. Всё, что говорит на Chrome DevTools Protocol (CDP — открытый протокол отладки браузера и Node), потом цепляется к этому сокету: Chrome через chrome://inspect, отдельное окно DevTools или JavaScript-отладчик VS Code. Отладчик — это клиент; твой процесс — сервер. Эта рамка объясняет следующие два факта, на которых люди обжигаются.

Первое: подключение асинхронно и занимает реальное стенное время. --inspect даёт твоему коду бежать сразу, так что быстро падающий баг старта успевает закончиться до того, как клиент подключится, — ровно случай из хука. Фикс — --inspect-brk, который включает агент и ломает до первой строки пользовательского кода, паркуя процесс, пока отладчик не подцепится и не скажет продолжить. Бери --inspect для долгоживущего сервера, к которому подцепишься на лету; бери --inspect-brk, когда баг в старте, на верхнем уровне модуля или в чём угодно, что выполняется один раз. (--inspect-wait — золотая середина: ждать подключения, но не ломать.)

Второе: адрес бинда — осознанный выбор. --inspect=0.0.0.0:9229 или --inspect=<публичный-ip> выставляет агент в сеть — читай дальше, потому что это одно изменение и есть разница между отладчиком и удалённым шеллом.

# подцепиться на лету к работающему серверу (localhost:9229)
node --inspect server.js

# заморозить до строки 1 и ждать отладчик — для багов старта
node --inspect-brk server.js

# свой бинд (тут всё ещё localhost; см. раздел безопасности до расширения)
node --inspect=127.0.0.1:9230 server.js

Брейкпоинты, оператор debugger и source maps

После подключения DevTools даёт полный набор: строчные брейкпоинты, условные брейкпоинты (срабатывать только при userId === 42), logpoint-ы (печатают выражение, не останавливаясь — брейкпоинт, который логирует вместо паузы), step over/into/out, живой список watch и Console-REPL, вычисляемый в области видимости остановленного фрейма, так что ты можешь читать и даже менять локальные переменные на брейкпоинте. Голый оператор debugger; в исходнике — это программный брейкпоинт: он ставит паузу, если отладчик подключён, и no-op в противном случае.

Ловушка для TypeScript и любого скомпилированного/собранного кода: отладчик видит сгенерированный JavaScript, так что брейкпоинты и фреймы стека приземляются в dist/app.js, а не в твой src/app.ts. Запускай с --enable-source-maps, чтобы Node читал файлы .js.map и перемапливал трассы стека — и позиции строк отладчика — обратно в исходник. Без этого продовая трасса стека указывает на минифицированную строку 1, колонку 9000, а твой брейкпоинт сидит в коде, который ты никогда не писал.

# сгенерированный JS + source maps → стеки и брейкпоинты мапятся в .ts
node --enable-source-maps --inspect-brk dist/app.js

util.debuglog: логи с нулевой ценой без отладчика

Иногда ты не хочешь останавливаться — ты хочешь трассу, которую можно включить в одном окружении и не платить за неё нигде больше. Это util.debuglog(section). Он возвращает логирующую функцию, которая является no-op, пока переменная окружения NODE_DEBUG не называет эту секцию — в выключенном состоянии она не делает форматирования строк и ничего не пишет, так что её фактически бесплатно оставить в горячих путях. Включай на запуск через NODE_DEBUG=mysection, перечисляй несколько через запятую (NODE_DEBUG=db,http) или используй wildcard-ы (NODE_DEBUG=db*). Вывод идёт в stderr с тегом секции и PID: DB 3245: query took 14ms. Само ядро Node использует ровно этот механизм — NODE_DEBUG=http,net,tls зажигает внутренние трассы рантайма.

import { debuglog } from "node:util";
const log = debuglog("db"); // no-op, пока нет NODE_DEBUG=db

async function query(sql) {
  const t = performance.now();
  const rows = await pool.query(sql);
  log("query took %dms (%d rows)", performance.now() - t, rows.length);
  return rows;
}
// запуск: NODE_DEBUG=db node app.js  → "DB 3245: query took 14ms (3 rows)"
// запуск: node app.js                → тишина, нулевые накладные

Навык — подбирать инструмент под момент. Таблица ниже — сеньорская решётка решений.

Режим сбоя: порт инспектора — это удалённый шелл

Вот правило, которое превращает инструмент отладки в инцидент: порт инспектора — это поверхность удалённого выполнения кода. Chrome DevTools Protocol включает Runtime.evaluate, который выполняет произвольные выражения внутри твоего процесса. Доки Node прямолинейны: если отладчик забиндён на публичный IP или 0.0.0.0, любой клиент, способный дотянуться до этого адреса, может подключиться без всякой аутентификации и выполнить произвольный код от имени твоего процесса. Нет ни пароля, ни токена — достижимость и есть авторизация.

Отсюда два неоспоримых правила. Никогда не бинди инспектор ни на что, кроме localhost, и никогда не оставляй --inspect включённым в проде. Дефолтный 127.0.0.1 безопасен именно потому, что дотянуться может только локальная машина; --inspect=0.0.0.0 это выбрасывает. Чтобы отладить удалённую машину, не расширяй бинд — туннелируй localhost-в-localhost через SSH (ssh -L 9221:localhost:9229 user@host), чтобы порт никогда не касался публичной сети. Флаг --inspect, случайно вшитый в продовый образ контейнера, или бинд на 0.0.0.0 на хосте с публичным интерфейсом — это полноценный RCE-бэкдор, который ни одно правило фаервола внутри приложения не закроет.