Отладка в VS Code: точки останова и launch.json

Как это работает

Отладчик VS Code останавливает программу в нужной строке и показывает её состояние: значения переменных, стек вызовов, результат выражений. Это быстрее и надёжнее, чем расставлять console.log или print и перезапускать код.

Всё настраивается в файле .vscode/launch.json. В нём лежит список конфигураций, каждая описывает один способ запуска:

• "request": "launch" — VS Code сам запускает программу под отладчиком;
• "request": "attach" — VS Code подключается к процессу, который уже работает.

Создать файл проще всего через панель Run and Debug: «create a launch.json file», затем выбрать среду. Запуск — F5, точка останова — F9 или клик слева от номера строки.

Node.js

Конфигурация для запуска скрипта:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Run server",
      "program": "${workspaceFolder}/src/index.js",
      "skipFiles": ["<node_internals>/**"],
      "env": { "NODE_ENV": "development" }
    }
  ]
}

• skipFiles не даёт отладчику заходить во внутренние модули Node.js при пошаговом выполнении.
• Для TypeScript нужны source maps: включите sourceMap в tsconfig.json, а в конфигурации укажите outFiles с путём к собранным .js.
• Если проект запускается через npm-скрипт, удобнее JavaScript Debug Terminal: любые команды, запущенные в нём, автоматически подключаются к отладчику.

Браузер

Для фронтенда VS Code запускает Chrome или Edge и отлаживает код прямо в редакторе:

{
  "type": "chrome",
  "request": "launch",
  "name": "Debug frontend",
  "url": "http://localhost:3000",
  "webRoot": "${workspaceFolder}"
}

Сначала запустите dev-сервер, затем эту конфигурацию. webRoot должен указывать на папку, относительно которой сервер отдаёт исходники, иначе точки останова не совпадут с файлами. Для Edge замените тип на msedge.

Python

Нужно расширение Python от Microsoft. В актуальных версиях отладчик называется debugpy, в старых конфигурациях можно встретить тип python.

{
  "type": "debugpy",
  "request": "launch",
  "name": "Python: current file",
  "program": "${file}",
  "console": "integratedTerminal"
}

Для Django или FastAPI вместо program используют "module" (например, uvicorn) и "args" с параметрами запуска. Проверьте, что в VS Code выбран правильный интерпретатор виртуального окружения.

Условные точки останова и logpoints

Правый клик слева от номера строки открывает варианты:

• Conditional Breakpoint → Expression — остановка только если выражение истинно, например user.id === 42 или len(items) > 100. Незаменимо в циклах.
• Hit Count — остановка на N-м проходе через строку.
• Logpoint — вместо остановки выводит сообщение в Debug Console. Выражения пишутся в фигурных скобках: Order {order.id}, total {order.total}. Код менять не нужно, и в коммит ничего не попадёт.

Logpoints особенно полезны, когда остановка ломает поведение: таймауты, сетевые запросы, анимации.

Watch, стек и Debug Console

Когда программа остановлена, в панели Run and Debug доступны:

• Variables — локальные и глобальные переменные текущей области;
• Watch — выражения, которые пересчитываются на каждом шаге: cart.items.length, response.status;
• Call Stack — цепочка вызовов; клик по кадру показывает его переменные;
• Debug Console — здесь можно выполнить любое выражение в контексте текущей точки.

Пошаговое выполнение: F10 — шаг с обходом функции, F11 — шаг внутрь, Shift+F11 — выход из функции, F5 — продолжить.

Подключение к запущенному процессу

Иногда программу запускает не VS Code: Docker, другой терминал, менеджер процессов. Тогда используйте attach.

Node.js: запустите процесс с флагом --inspect (или --inspect-brk, чтобы он ждал отладчик на первой строке):

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Node",
  "port": 9229
}

Можно также указать "processId": "${command:PickProcess}" и выбрать процесс из списка.

Python: запустите python -m debugpy --listen 5678 --wait-for-client app.py и подключитесь конфигурацией с "request": "attach" и "connect": { "host": "localhost", "port": 5678 }.

Для процесса внутри контейнера пробросьте порт отладчика и настройте localRoot/remoteRoot (Node.js) или pathMappings (Python), чтобы пути в контейнере совпали с файлами в проекте. Не открывайте порт отладчика наружу на рабочих серверах: через него можно выполнить произвольный код.

Частые проблемы

• Точка останова серая, «unbound» — отладчик не сопоставил файл: проверьте source maps, webRoot, outFiles или пути в контейнере.
• Программа завершается до точки останова — используйте --inspect-brk или --wait-for-client.
• Python не видит пакеты — выбран не тот интерпретатор.