Отладка Node.js в Visual Studio Code

Женщина работает за MacBook Pro

Краткое содержание:

Подготовка окружения и требования
Быстрый запуск отладки в VS Code
Конфигурация launch.json и основные опции
Подключение внешнего процесса и режим inspect
Точки останова и их управление
Отладка TypeScript с source maps
Чеклисты, советы и методология расследования проблем

Что нужно подготовить

Прежде чем начать, установите последнюю версию Node.js и Visual Studio Code на локальную машину. Node.js можно скачать с официального сайта Node.js, а VS Code — с официального сайта Visual Studio Code. Для Windows и macOS есть отдельные инструкции по установке — следуйте официальным гайдам.

Нужен проект на Node.js. Можно создать минимальное приложение вручную или использовать уже имеющийся проект. Для TypeScript-проектов убедитесь, что есть tsconfig.json и что включены source maps.

Важно: версия Node.js и расширения VS Code (если используются) влияют на доступные возможности отладчика. Если используете ts-node, nodemon или Docker, обратите внимание на специальные настройки ниже.

Быстрый старт: запуск сессии отладки

Откройте проект в VS Code.
Нажмите иконку “Run and Debug” в боковой панели или клавиши Ctrl + Shift + D.
Нажмите кнопку “Run and Debug”.

VS Code попытается автоматически определить окружение. Если автоматическое обнаружение не сработало, выберите Node.js.

Скриншот отладчика в VS Code

После выбора окружения VS Code активирует отладчик и подключится к процессу. Вы увидите вывод в панели DEBUG CONSOLE. Через отладочную панель в верхней части можно пошагово выполнять код, ставить паузу и завершать сессию.

Примечание: если у вас несколько конфигураций, используйте всплывающее меню конфигураций в панели Run and Debug.

Конфигурация launch.json и основные опции

Файл launch.json определяет, как запускать и подключать приложения для отладки. Пример минимальной конфигурации для простого Node.js приложения:

{   
  "version": "0.2.0",   
  "configurations": [   
    { "type": "node",   
      "request": "launch",   
      "name": "Launch Program",   
      "skipFiles": [ "/" ],   
      "program": "${workspaceFolder}\\index.js"  
    }   
  ]  
}

Ключевые параметры, на которые стоит обратить внимание:

type — тип отладчика (node, pwa-node и т.д.).
request — launch для запуска или attach для подключения к уже запущенному процессу.
program — путь к основной точке входа вашего приложения.
args — массив аргументов командной строки для программы.
runtimeArgs — аргументы для Node.js (например, включение ts-node).
env и envFile — переменные окружения.
skipFiles — файлы/папки, которые отладчик должен пропустить.
outFiles — шаблон для поиска сгенерированных JS-файлов при отладке TypeScript.

Совет: храните несколько конфигураций в одном launch.json — например “Debug: Dev” и “Debug: Prod” с разными переменными окружения.

Пять панелей отладчика и где что искать

В левой части окна отладчика обычно видны пять панелей: VARIABLES, WATCH, CALL STACK, LOADED SCRIPTS и BREAKPOINTS.

VARIABLES — локальные и глобальные переменные на текущем стеке.
WATCH — выражения, за которыми вы хотите следить.
CALL STACK — стек вызовов; помогает понять, как вы попали в текущую точку.
LOADED SCRIPTS — все загруженные скрипты и их пути.
BREAKPOINTS — список всех точек останова и их свойств.

Подключение к внешнему процессу (attach)

Иногда нужно отлаживать уже запущенное приложение. Запустите приложение с флагом inspect:

node --inspect index.js

Если хотите остановить выполнение до первой строки, добавьте флаг –inspect-brk:

node --inspect-brk index.js

Затем в VS Code откройте палитру команд (Ctrl + Shift + P) и запустите команду Debug: Attach to Node.js process. Выберите нужный процесс в списке.

Если процесс запущен в контейнере Docker или на удалённой машине, используйте порт-проброс (ssh -L) или remote debugging и укажите host/port в конфигурации attach.

Пример конфигурации attach:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Process",
      "port": 9229,
      "address": "localhost",
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/usr/src/app"
    }
  ]
}

Точки останова: как ставить и какие бывают

Точку останова можно поставить почти в любой строке — в объявлениях переменных, выражениях и даже в комментариях (если строка содержит исполняемый код). Нельзя ставить точку останова в объявлении функции до её использования в строке вызова.

Чтобы поставить точку останова, наведите курсор влево от номера строки и кликните — появится красный кружок.

Типы точек останова:

Обычные точки останова — останавливают выполнение.
Условные — срабатывают только при выполнении условия (укажите выражение).
Логирующие — не останавливают выполнение, но печатают сообщение в DEBUG CONSOLE.
Исключения — остановка при выбросе исключения или при непойманном исключении.

В панели BREAKPOINTS можно активировать/деактивировать точки, задать условие или лог-сообщение.

Пример: пошаговая сессия отладки

Установите точки останова в ключевых местах (вход в функцию, перед возвратом, при обращении к базе данных).
Нажмите Launch или подключитесь через attach.
Отслеживайте переменные и выражения в панели VARIABLES/WATCH.
Используйте Call Stack, чтобы понять путь выполнения.
Если нужно, редактируйте код и перезапустите сессию или используйте hot-reload (например, nodemon).

Для продолжения исполнения нажмите Continue или F5.

Отладка TypeScript через source maps

Если проект написан на TypeScript, включите генерацию source maps в tsconfig.json:

{ "compilerOptions": { "sourceMap": true }}

Параметр outFiles в launch.json подскажет VS Code, где искать сгенерированные .js и .map файлы:

{   
  "version": "0.2.0",   
  "configurations": [ {   
    "type": "node",   
    "request": "launch",   
    "name": "Launch Program",   
    "skipFiles": [ "/" ],   
    "program": "${workspaceFolder}\\index.js",   
    "outFiles": ["${workspaceFolder}\\dist\\**\\*.js"]   
    }   
  ]  
}

Если вы используете ts-node (запуск без сборки), используйте конфигурацию с runtimeArgs, регистрирующим ts-node:

{   
  "version": "0.2.0",   
  "configurations": [ {   
    "type": "pwa-node",   
    "request": "launch",   
    "name": "Launch Server",   
    "skipFiles": [ "/**" ],   
    "runtimeArgs": [ "-r", "ts-node/register" ],   
    "args": [ "${workspaceFolder}/src/server.ts" ]   
  }]  
}

Обратите внимание: для pwa-node требуется более новая версия отладчика. Если видите несоответствие номеров строк, проверьте, что sourceMap действительно генерируется и что пути в outFiles совпадают.

Частые проблемы и быстрые решения

Важно: не меняйте файлы в node_modules вручную. Для воспроизводимых настроек используйте конфигурации и переменные окружения.

Проблема: Breakpoint не срабатывает

Убедитесь, что отладчик подключён к правильному процессу.
Проверьте, что source maps присутствуют и пути в outFiles правильные.
Если используете транспиляцию, проверьте соответствие номеров строк.

Проблема: Невозможно подключиться по порту

Проверьте, что Node запущен с –inspect и порт открыт (9229 по умолчанию).
Для Docker-приложений пробросьте порт.
Удостоверьтесь, что нет конфликта с фаерволом.

Проблема: Медленная отладка

Отключите ненужные точки останова.
Исключите heavy I/O операции при шаговой отладке.
Для больших проектов используйте фильтрацию в skipFiles.

Методология расследования проблем: мини-плейбук

Сформулируйте ожидаемое поведение и шаги для воспроизведения.
Установите минимальный набор точек останова, чтобы локализовать проблему.
Смотрите значения в WATCH и VARIABLES, фиксируйте подозрительные данные.
Просмотрите Call Stack для понимания пути выполнения.
Если дело в трансляции (TS → JS), проверьте source maps и соответствие версий компилятора.
Повторяйте, пока не найдете причину; минимизируйте влияние изменений и документируйте найденное.

Чеклисты по ролям

Разработчик:

Установлена последняя стабильная версия Node.js
Открыт рабочий каталог в VS Code
Настроен launch.json с основной конфигурацией
Настроены source maps для TypeScript

QA-инженер:

Есть сценарии воспроизведения для багов
Точки останова и логирование установлены в критических местах
Проведена регресс-тестовая сессия в режиме отладки

Операции/DevOps:

Проброшены порты для remote debugging
Конфигурация для attach хранится в пайплайне/документации
Проверен доступ к логам и консоли контейнера

Полезные правила и эвристики

Минимизируйте количество активных breakpoint’ов — это снижает шум.
Сначала локализуйте проблему «от широкого к узкому»: глобальные точки, затем локализованные.
Если проблема не воспроизводится в локальном окружении, проверьте отличия конфигурации среды.

Шпаргалка: конфигурации и команды

Запуск с отладчиком локально: node –inspect index.js
Остановка перед первой строкой: node –inspect-brk index.js
Attach через порт: настройка request: “attach”, port: 9229
TS без сборки: runtimeArgs: [“-r”,”ts-node/register”]

Когда встроенный отладчик не подходит

Контрпримеры и альтернативы:

Если нужно профилирование производительности — используйте Node.js профилировщик (Inspector, Clinic.js) или внешние APM.
Для распределённых трейсингов используйте OpenTelemetry и соответствующие инструменты визуализации.
Если код выполняется в production и нельзя подключать отладчик — собирайте расширенные логи и снимки стека.

Критерии приёмки

Отладчик может подключаться к локальному приложению и останавливать выполнение в нужных точках.
Для TypeScript точки останова соответствуют исходным .ts файлам.
Инструкции восстановления и подключения описаны в README проекта.

Глоссарий (1 строка)

source map — файл, связывающий скомпилированный JS с исходным TS для корректной отладки.

Частые вопросы

Q: Можно ли отлаживать приложение внутри Docker-контейнера? A: Да. Пробросьте порт отладки (обычно 9229) и используйте конфигурацию attach с указанием address/port и remoteRoot/localRoot.

Q: Что делать, если номера строк не совпадают с исходниками? A: Проверьте генерацию source maps, правильность путей в outFiles и настройку компилятора TypeScript.

Q: Нужно ли ставить точки останова в node_modules? A: Обычно нет. Для отладки библиотек лучше клонировать пакет и отлаживать локально.

Краткое резюме

Отладка Node.js в VS Code — доступный и мощный инструмент для разработчиков. Используйте launch.json для сохранения конфигураций, source maps для TypeScript, и attach для внешних процессов. Следуйте плейбуку диагностики и ролям-чеклистам для быстрого и безопасного устранения ошибок.

Важно: если шаги не помогают, документируйте воспроизведение и создавайте минимальный репозиторий-пример — это сильно ускорит анализ.