Отладка Node.js

Это руководство поможет вам начать отлаживать приложения и скрипты на Node.js.

Запущенный с ключом --inspect, процесс Node.js слушает подключения отладочного клиента. По умолчанию он слушает на хосте и порту 127.0.0.1:9229. Каждому процессу также присваивается уникальный UUID.

Клиентам Inspector необходимо знать и указывать адрес хоста, порт и UUID для подключения. Полный URL выглядит примерно так: ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.

Node.js также начнёт слушать отладочные сообщения, если получит сигнал SIGUSR1. (SIGUSR1 недоступен в Windows.) В Node.js 7 и более ранних версиях это активирует устаревший Debugger API. В Node.js 8 и новее это активирует Inspector API.

Поскольку отладчик имеет полный доступ к среде выполнения Node.js, злоумышленник, способный подключиться к этому порту, может выполнить произвольный код от имени процесса Node.js. Важно понимать последствия для безопасности при открытии порта отладчика в публичных и частных сетях.

Если отладчик привязан к публичному IP-адресу или к 0.0.0.0, любые клиенты, которые могут достучаться до вашего IP-адреса, смогут без ограничений подключиться к отладчику и выполнить произвольный код.

По умолчанию node --inspect привязывается к 127.0.0.1. Публичный IP-адрес или 0.0.0.0 и т. п. нужно указывать явно, если вы намерены разрешить внешние подключения к отладчику. Это может подвергнуть вас потенциально серьёзной угрозе безопасности. Рекомендуем убедиться, что настроены подходящие межсетевые экраны и контроль доступа, чтобы не допустить бреши в безопасности.

О том, как безопасно разрешить подключение удалённых отладочных клиентов, см. раздел «Сценарии удалённой отладки».

Даже если вы привяжете порт inspector к 127.0.0.1 (значение по умолчанию), любые приложения, работающие локально на вашей машине, получат неограниченный доступ. Так задумано, чтобы локальные отладчики могли удобно подключаться.

Сайты, открытые в веб-браузере, могут делать WebSocket- и HTTP-запросы в рамках модели безопасности браузера. Начальное HTTP-соединение необходимо, чтобы получить уникальный идентификатор отладочной сессии. Политика одного источника (same-origin) не даёт сайтам установить это HTTP-соединение. Для дополнительной защиты от атак DNS rebinding Node.js проверяет, что заголовки Host для соединения содержат либо IP-адрес, либо в точности localhost.

Эти политики безопасности запрещают подключаться к удалённому серверу отладки по имени хоста. Обойти это ограничение можно, указав либо IP-адрес, либо используя ssh-туннели, как описано ниже.

Минимальный отладчик из командной строки доступен через node inspect myscript.js. К Node.js Inspector также могут подключаться несколько коммерческих и open source инструментов.

• Откройте chrome://inspect (edge://inspect в Microsoft Edge) в браузере.
• Нажмите кнопку Configure и убедитесь, что ваш целевой хост и порт есть в списке.
• Ваше приложение на Node.js должно появиться в списке Remote Target.

• Зайдите на http://localhost:<inspect-port>/json/list. Должен вернуться JSON-объект, содержащий devtoolsFrontendUrl.
• Скопируйте значение devtoolsFrontendUrl из ответа и вставьте его в адресную строку браузера.

Подробнее см. Chrome DevTools Frontend и руководство по Microsoft Edge DevTools.

• На панели Debug нажмите значок настроек, чтобы открыть .vscode/launch.json. Для начальной настройки выберите «Node.js».

Подробнее см. https://code.visualstudio.com/docs/nodejs/nodejs-debugging.

• Выберите в меню «Debug > Start Debugging» или нажмите F5.
• Подробная инструкция.

• Создайте новую конфигурацию отладки Node.js и нажмите Debug. Для Node.js 7+ по умолчанию будет использоваться --inspect. Чтобы отключить, снимите флажок js.debugger.node.use.inspect в реестре IDE (Registry). Подробнее о запуске и отладке Node.js в WebStorm и других IDE от JetBrains см. в онлайн-справке WebStorm.

• Библиотека, упрощающая подключение к эндпоинтам Inspector Protocol.

Подробнее см. https://github.com/cyrus-and/chrome-remote-interface.

• Из .js-файла выберите «Debug As... > Node program» или
• Создайте конфигурацию отладки, чтобы подключить отладчик к уже запущенному приложению Node.js (стартовавшему с --inspect).

Подробнее см. https://eclipseide.org/.

В следующей таблице перечислено влияние различных runtime-флагов на отладку:

Мы рекомендуем никогда не заставлять отладчик слушать на публичном IP-адресе. Если вам нужно разрешить удалённые подключения для отладки, мы рекомендуем вместо этого использовать ssh-туннели. Следующий пример приводится исключительно в иллюстративных целях. Прежде чем продолжить, осознайте риск для безопасности при предоставлении удалённого доступа к привилегированному сервису.

Допустим, вы запускаете Node.js на удалённой машине remote.example.com, которую хотите отлаживать. На этой машине следует запустить процесс node с inspector, слушающим только localhost (значение по умолчанию).

node --inspect server.js

Теперь на локальной машине, с которой вы хотите инициировать подключение отладочного клиента, можно поднять ssh-туннель:

ssh -L 9221:localhost:9229 user@remote.example.com

Это запускает сессию ssh-туннеля, в которой подключение к порту 9221 на вашей локальной машине будет перенаправлено на порт 9229 на remote.example.com. Теперь вы можете подключить отладчик, например Chrome DevTools или Visual Studio Code, к localhost:9221, и он сможет отлаживать так, как будто приложение Node.js работает локально.

Устаревший отладчик признан нерекомендуемым начиная с Node.js 7.7.0. Пожалуйста, используйте вместо него --inspect и Inspector.

При запуске с ключами --debug или --debug-brk в версии 7 и более ранних Node.js слушает отладочные команды закрытого V8 Debugging Protocol на TCP-порту, по умолчанию 5858. Любой отладочный клиент, понимающий этот протокол, может подключиться к работающему процессу и отлаживать его; пара популярных перечислена ниже.

V8 Debugging Protocol больше не поддерживается и не документируется.

Запустите node debug script_name.js, чтобы отлаживать скрипт во встроенном отладчике командной строки. Ваш скрипт запускается в другом процессе Node.js, стартовавшем с опцией --debug-brk, а исходный процесс Node.js выполняет скрипт _debugger.js и подключается к цели. Подробнее см. документацию.

Отлаживайте приложение Node.js в Chrome DevTools с помощью промежуточного процесса, который транслирует Inspector Protocol, используемый в Chromium, в протокол V8 Debugger, используемый в Node.js. Подробнее см. https://github.com/node-inspector/node-inspector.