Отладка: breakpoints, console и чтение stack trace

Самая дорогая привычка начинающего — менять код наугад, пока ошибка не исчезнет. Иногда она исчезает, но причина остаётся и возвращается в другом месте. Отладка (debugging) — это короткий цикл из четырёх шагов, который работает на любом языке.

Разберём цикл на учебной программе: она считает сумму заказа в кофейне с доставкой и промокодом. В ней три намеренных бага разного вида: падение с исключением, неверный результат из-за типов и условие, которое никогда не срабатывает.

export function calcSubtotal(items) {
  let total = 0;
  for (let i = 0; i <= items.length; i++) {
    total += items[i].price * items[i].qty;
  }
  return total;
}

export function addDelivery(subtotal, delivery) {
  return subtotal + delivery;
}

export function applyPromo(total, code) {
  if (code === "sale") return Math.round(total * 0.9);
  return total;
}

export function checkout(cart) {
  const subtotal = calcSubtotal(cart.items);
  const withDelivery = addDelivery(subtotal, cart.delivery);
  return applyPromo(withDelivery, cart.promo);
}

import { checkout } from "./cart.mjs";

const cart = {
  items: [
    { name: "latte", price: 1500, qty: 2 },
    { name: "croissant", price: 1200, qty: 1 },
  ],
  delivery: "500",
  promo: "SALE",
};

console.log("Total:", checkout(cart));

Запускаем node main.mjs и получаем падение. Вывод — реальный, с Node.js 24; длинный путь к папке заменён на …:

$ node main.mjs
file:///…/cart.mjs:4
    total += items[i].price * items[i].qty;
                      ^

TypeError: Cannot read properties of undefined (reading 'price')
    at calcSubtotal (file:///…/cart.mjs:4:23)
    at checkout (file:///…/cart.mjs:19:20)
    at file:///…/main.mjs:12:23
    at ModuleJob.run (node:internal/modules/esm/module_job:439:25)
    at async node:internal/modules/esm/loader:643:26
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)

Node.js v24.18.0

По документации Node.js первая строка стека имеет вид «класс ошибки: сообщение», а дальше идут кадры (frames), каждый начинается с at. Самый свежий вызов наверху, точка входа — внизу. Правило чтения: найдите первую строку at с вашим файлом, а не с node:internal или node_modules. Это место, где сломалось, хотя причина может быть выше по стеку — в том, кто передал плохие данные.

Гипотеза: на какой-то итерации items[i] равен undefined. В массиве два элемента с индексами 0 и 1, а условие i <= items.length пускает цикл и на индекс 2. Это классическая ошибка «на единицу» (off-by-one). Исправление — строгое <.

После исправления цикла программа выводит Total: 4200500. Исключения нет, но результат абсурдный. Stack trace не появится — сужать придётся самим. Самый быстрый инструмент — временный вывод значений прямо перед подозрительным местом. console.table показывает массив объектов таблицей, а typeof — тип значения:

console.table(cart.items);
console.log("delivery:", cart.delivery, typeof cart.delivery);

$ node main.mjs
┌─────────┬─────────────┬───────┬─────┐
│ (index) │ name        │ price │ qty │
├─────────┼─────────────┼───────┼─────┤
│ 0       │ 'latte'     │ 1500  │ 2   │
│ 1       │ 'croissant' │ 1200  │ 1   │
└─────────┴─────────────┴───────┴─────┘
delivery: 500 string
Total: 4200500

Гипотеза подтверждена: delivery — строка "500", и оператор + склеивает 4200 и "500" в "4200500". Такие данные часто приходят из форм, query-параметров и JSON, где число записано в кавычках. Исправляем на границе — приводим к числу там, где значение входит в расчёт:

--- a/cart.mjs
+++ b/cart.mjs
@@ -1,11 +1,11 @@
 export function calcSubtotal(items) {
   let total = 0;
-  for (let i = 0; i <= items.length; i++) {
+  for (let i = 0; i < items.length; i++) {
     total += items[i].price * items[i].qty;
   }
   return total;
 }

 export function addDelivery(subtotal, delivery) {
-  return subtotal + delivery;
+  return subtotal + Number(delivery);
 }

$ node main.mjs
Total: 4700

Итог 4700 — без скидки. Ошибки нет, все типы числа. Нужно остановить программу внутри applyPromo и посмотреть, что в ней происходит. Breakpoint (точка останова) — место, где отладчик ставит выполнение на паузу до выполнения строки. Самый простой способ — инструкция debugger;: она работает как breakpoint, если подключён отладчик, и ничего не делает без него.

Добавим debugger; первой строкой applyPromo и запустим встроенный консольный отладчик Node.js — node inspect. Ниже реальная сессия: cont — продолжить до следующей остановки, bt — стек вызовов, exec — вычислить выражение, watch — следить за значением, next — шаг на следующую строку.

$ node inspect main.mjs
< Debugger listening on ws://127.0.0.1:9229/31bee525-ecb9-4a6c-b9ea-f75545b276bf
< For help, see: https://nodejs.org/learn/getting-started/debugging
< 
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
< 
debug> Break on start in cart.mjs:1
> 1 export function calcSubtotal(items) {
  2   let total = 0;
  3   for (let i = 0; i < items.length; i++) {
debug> cont
debug> break in cart.mjs:14
 12 
 13 export function applyPromo(total, code) {
>14   debugger;
 15   if (code === "sale") return Math.round(total * 0.9);
 16   return total;
debug> bt
#0 applyPromo cart.mjs:14:2
#1 checkout cart.mjs:22:9
#2 (anonymous) main.mjs:12:22
#3 run node:internal/modules/esm/module_job:439:24
debug> exec code
'SALE'
debug> exec code === "sale"
false
debug> watch('total')
debug> next
debug> step in cart.mjs:15
Watchers:
  0: total = 4700

 13 export function applyPromo(total, code) {
 14   debugger;
>15   if (code === "sale") return Math.round(total * 0.9);
 16   return total;
 17 }
debug> cont
debug> < Total: 4700
< 
debug> < Waiting for the debugger to disconnect...
< 
debug> .exit

Факты из отладчика: code равен 'SALE', а сравнение с "sale" даёт false — регистр не совпадает. Стек bt показывает ту же цепочку, что и stack trace: applyPromo ← checkout ← main.mjs. Исправляем сравнение и убираем debugger;:

-  if (code === "sale") return Math.round(total * 0.9);
+  if (code?.trim().toLowerCase() === "sale") return Math.round(total * 0.9);

$ node main.mjs
Total: 4230

Консольный отладчик полезен, чтобы понять механику, но в работе удобнее графический. Под капотом он тот же: Node.js с флагом --inspect открывает порт для отладчика, и к нему подключаются Chrome DevTools или VS Code. По умолчанию это 127.0.0.1:9229. Флаг --inspect-brk дополнительно останавливает программу до первой строки вашего кода, чтобы успеть расставить breakpoints:

$ node --inspect-brk main.mjs
Debugger listening on ws://127.0.0.1:9229/5f699728-1ccb-4e05-ba8a-2afa59a35332
For help, see: https://nodejs.org/learn/getting-started/debugging

• Остановка на исключениях: в DevTools можно включить паузу на перехваченных и неперехваченных исключениях — отладчик остановится там, где ошибка брошена, со всеми переменными.
• Restart frame в DevTools перезапускает текущую функцию без перезапуска всей программы — удобно, чтобы пройти её ещё раз после изменения значения в Scope.
• Условный breakpoint вроде i === items.length в цикле из бага 1 остановит программу ровно на проблемной итерации, а не на каждой.

Если ошибка в веб-приложении связана с данными с сервера, начните с вкладки Network в DevTools: статус-код, тело запроса и ответа часто сразу показывают, на чьей стороне проблема. Подробно о запросах, статусах и JSON — в уроке «HTTP и JSON».