Отладка Node.js в VS Code

Разработчица за MacBook Pro, работающая с кодом

Краткое описание

Встроенный отладчик Visual Studio Code позволяет выполнять пошаговую отладку приложений, которые работают на Node.js. Это значит, что вы можете исследовать поведение JavaScript-кода, а также кода, транспилированного в JavaScript (например, TypeScript). В статье рассмотрены: запуск сессии, настройка launch.json, подключение к внешним процессам, работа с точками останова, использование source maps и рекомендации для контейнеров и удалённой отладки.

Важно: базовые примеры подходят как для Windows, так и для macOS/Linux; пути в конфигурации можно адаптировать под ОС.

Что потребуется

Установленный Node.js (рекомендуется LTS-версия). Скачать на официальном сайте Node.js.
Visual Studio Code последней версии. Скачать с сайта VS Code.
Проект Node.js: новый или существующий (index.js, package.json и т. п.).

Совет: если вы используете TypeScript, заранее настройте tsconfig.json и опцию sourceMap.

Базовый процесс отладки в VS Code

Откройте папку проекта в VS Code.
Нажмите иконку “Запуск и отладка” в боковой панели или используйте сочетание клавиш Ctrl+Shift+D (Cmd+Shift+D на macOS).
В верхней части панели нажмите кнопку “Запуск и отладка”/Run and Debug, выберите среду Node.js, если VS Code не определил её автоматически.

При успешном выборе среды отладчик подключится к процессу, а вывод будет отображён в DEBUG CONSOLE. Панель отладки предоставляет тулбар для поштупного выполнения, продолжения (F5), пошагового входа (F11), выхода (Shift+F11) и пошагового перехода (F10).

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

launch.json — файл конфигурации

launch.json позволяет задать параметры запуска/подключения отладчика. Ниже — несколько типовых конфигураций, которые вы можете адаптировать под проект. Сохраните их в .vscode/launch.json.

Пример простого запуска (Windows-пути в программе — при необходимости замените на POSIX-пути для macOS/Linux):

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

Если у вас Linux/macOS, используйте прямые слэши в program: “${workspaceFolder}/index.js”.

Важно: параметр skipFiles помогает скрыть внутренние файлы Node.js при отладке и ускоряет симптомы.

Панели отладчика и их назначение

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

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

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

Иногда нужно отлаживать уже запущенный процесс (например, сервер, запущенный командой node или процесс в контейнере). Запустите Node.js с флагом –inspect:

node --inspect index.js

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

node --inspect-brk index.js

Далее в VS Code откройте палитру команд Ctrl+Shift+P и выберите Debug: Attach to Node.js process. Появится список доступных Node-процессов; выберите нужный.

Совет: при отладке в контейнере откройте проброс порта (по умолчанию 9229) и подключайтесь к localhost:9229.

Создание и управление точками останова

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

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

Варианты точек останова:

Обычные (стоп при достижении).
Условные (стоп при выполнении условия).
Logpoints (не останавливают, а записывают сообщение в консоль, полезно вместо console.log).

Пример условной точки останова: укажите выражение x > 10 — отладчик остановится только если условие истинно.

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

Поставьте точку останова в месте, где предполагаете проблему.
Запустите конфигурацию Launch или подключитесь к процессу.
Когда выполнение остановится, посмотрите VARIABLES и CALL STACK.
Используйте WATCH, чтобы отслеживать выражения.
В DEBUG CONSOLE можно выполнять выражения на лету.
По необходимости измените значения переменных в окне VARIABLES (runtime edit) и продолжите выполнение.

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

Чтобы отлаживать исходный TypeScript, включите генерацию source maps. В корне проекта создайте или обновите tsconfig.json:

{
  "compilerOptions": {
    "sourceMap": true,
    "outDir": "dist"
  }
}

После сборки ваши .js-файлы из outDir будут сопровождаться .js.map; VS Code сопоставит исходники .ts и выполнит отображение в отладчике.

Если генерация и структура файлов сложнее, укажите outFiles в launch.json, чтобы явно указать, где искать скомпилированные файлы и карты:

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

Если вы используете ts-node для запуска TypeScript без предварительной сборки, используйте конфигурацию pwa-node и загрузку ts-node/register:

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

Важно: для больших проектов рекомендуем явную сборку с outDir и корректными путями в outFiles — это упрощает сопоставление и ускоряет отладку.

Отладка с пересборкой (nodemon) и автоматическим перезапуском

Если вы используете nodemon для авто-перезапуска, запускайте его с флагом –inspect и укажите путь к точке входа. Пример конфигурации для nodemon + ts-node:

package.json (скрипт):

{
  "scripts": {
    "dev": "nodemon --inspect -r ts-node/register src/server.ts"
  }
}

Для attach-подключения используйте типичную конфигурацию attach в launch.json, указывая порт 9229 или другой, если вы его переназначили.

Отладка в Docker и удалённо

Пробросьте порт отладки (по умолчанию 9229) из контейнера на хост.
Запустите Node.js в контейнере с –inspect=0.0.0.0:9229 или –inspect-brk=0.0.0.0:9229.
В launch.json создайте конфигурацию типа “attach” и укажите address/port:

{
  "name": "Attach to Docker",
  "type": "node",
  "request": "attach",
  "address": "localhost",
  "port": 9229,
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/usr/src/app"
}

localRoot и remoteRoot помогают VS Code сопоставлять исходники локально и в контейнере.

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

VS Code не видит процесс: убедитесь, что Node.js запущен с –inspect и порт не блокируется брандмауэром.
Точки останова не срабатывают: проверьте, что сгенерированы source maps и верны пути в outFiles.
“Cannot find source file” при отладке TypeScript: проверьте поля sourceRoot и включение sourceMap в tsconfig.
Неправильные пути в launch.json: используйте ${workspaceFolder} и относительные пути вместо абсолютных.

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

Отладка на очень высокой нагрузке: поведение приложения под отладчиком может отличаться от production; для нагрузочного анализа лучше использовать APM/профилировщики.
Сложные многопроцессные архитектуры (кластер, worker threads) требуют дополнительных настроек или внешних инструментов.

Методики и эвристики при локализации причин ошибок

Уменьшайте область поиска: делайте бинч-тесты и ставьте точки останова ближе к входу данных.
Сравните успешный и неуспешный сценарии: используйте print/logpoints для быстрого сравнения состояния.
Используйте контрольные точки (assert) для раннего выявления некорректных предположений.

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

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

Запущен Node.js с –inspect при необходимости.
Наличие актуальных source maps (для TS).
Настроен launch.json и проверен путь program/outFiles.
Точки останова расставлены в ключевых местах.

QA-инженер:

Умеет запускать сборки с флагами отладки.
Может подключаться к инстансу на тестовом окружении.
Использует логпоинты для неинвазивного сбора данных.

DevOps/инженер инфраструктуры:

Проброс портов для отладки в контейнере/VM.
Мониторинг и бэкап конфигураций отладки.

Инцидентный план: быстрый playbook для отладки в проде

Идентифицировать сервис и версию кода.
Включить режим отладки только на реплике/копии (не на всей продовой группе).
Пробросить порт 9229 (без публичного доступа) и ограничить IP.
Подключиться через VS Code как attach и поставить точку останова у входа запроса.
Собрать минимальные данные, воспроизвести проблему, отключить отладку.
Откатить конфигурацию и уведомить команду.

Важно: никогда не оставляйте открытый порт отладки в окружении, доступном извне.

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

Отладочная конфигурация запускается без ошибок и подключается к процессу.
Исходные файлы TypeScript корректно сопоставляются с сгенерированными JavaScript через source maps.
Точки останова срабатывают в ожидаемых местах и позволяют просмотреть стек и переменные.

Небольшая галерея крайних случаев

Асинхронные тайминги: логические ошибки в setTimeout/Promise могут требовать особых точек останова.
Worker threads: каждый воркер — отдельный процесс/контекст, требующий отдельного attach.
Генерация кода (babel, webpack): убедитесь, что source maps включены и корректно настроены.

Короткий глоссарий (1 строка на термин)

source map — файл, который связывает транспилированный JS с исходным TS для отладки.
launch.json — файл конфигурации отладки VS Code.
attach — режим подключения отладчика к уже запущенному процессу.
logpoint — точка логирования, не останавливающая выполнение.

Безопасность и конфиденциальность

Не включайте отладочные порты в публичный доступ.
Отключайте отладку после расследования инцидента.
Не выводите в консоль чувствительные данные (пароли, токены) — используйте маскирование при логировании.

Быстрые шаблоны и сниппеты (cheat sheet)

Запуск с отладкой: node –inspect index.js
Запуск и ожидание перед стартом: node –inspect-brk index.js
Запуск ts-node с nodemon: nodemon –inspect -r ts-node/register src/server.ts

Решение: если отладчик долго не подключается

Проверьте, слушает ли процесс порт: netstat -an | grep 9229 (или эквивалент в вашей ОС).
Убедитесь, что параметр –inspect использует 0.0.0.0 при запуске в контейнере.
Проверьте, что localRoot/remoteRoot настроены верно для контейнера.

Итог

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

Ключевые рекомендации:

Всегда используйте source maps для TypeScript.
Указывайте outFiles при сложной структуре сборки.
Для контейнеров применяйте localRoot/remoteRoot.

Спасибо за внимание. Если нужно, я подготовлю готовый launch.json, адаптированный для вашего проекта.

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