Отладка Node.js
Добавить в избранное
Включение инспектора
При запуске с ключом "--inspect", процесс Node.js прослушивает подключения от отладочного клиента. По умолчанию он будет слушать на хосте и порту "127.0.0.1:9229". Каждому процессу также назначается уникальный UUID.
Клиенты инспектора должны знать и указывать адрес хоста, порт и UUID для подключения. Полный URL будет выглядеть примерно так: "ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e".
Node.js также начинает прослушивать отладочные сообщения при получении сигнала "SIGUSR1". (SIGUSR1 недоступен в Windows.) В Node.js 7 и ранее это активирует устаревший API отладчика. В Node.js 8 и позднее активируется API инспектора.
Вопросы безопасности
Поскольку отладчик имеет полный доступ к среде выполнения Node.js, злонамеренный актор, способный подключиться к этому порту, может выполнить произвольный код от имени процесса Node.js. Важно понимать последствия безопасности при открытии порта отладчика в публичных и частных сетях.
Открытие порта отладки в публичных сетях небезопасно
Если отладчик привязан к публичному IP-адресу или к "0.0.0.0", любые клиенты, которые могут достичь вашего IP-адреса, смогут подключиться к отладчику без ограничений и смогут выполнять произвольный код.
По умолчанию "node --inspect" привязывается к "127.0.0.1". Вы должны явно указать публичный IP-адрес или "0.0.0.0", если хотите разрешить внешние подключения к отладчику. Это может подвергнуть вас значительной угрозе безопасности. Мы рекомендуем убедиться, что у вас есть соответствующие брандмауэры и средства управления доступом для предотвращения угроз безопасности.
Локальные приложения имеют полный доступ к инспектору
Даже если вы привяжете порт инспектора к "127.0.0.1" (по умолчанию), любые приложения, работающие локально на вашем компьютере, будут иметь неограниченный доступ. Это сделано для удобства подключения локальных отладчиков.
Браузеры, WebSockets и политика одного происхождения
Веб-сайты, открытые в веб-браузере, могут делать запросы WebSocket и HTTP в рамках модели безопасности браузера. Для получения уникального идентификатора сеанса отладки необходим начальный HTTP-запрос. Политика одного происхождения предотвращает возможность выполнения этого HTTP-запроса веб-сайтами. Для дополнительной безопасности против атак с подменой DNS Node.js проверяет, что заголовки "Host" для соединения указывают либо IP-адрес, либо "localhost" точно.
Эти политики безопасности не позволяют подключаться к удалённому серверу отладки, указывая имя хоста. Вы можете обойти это ограничение, указав либо IP-адрес, либо используя SSH-туннели, как описано ниже.
Клиенты инспектора
Минимальный отладчик CLI доступен с помощью "node inspect myscript.js". Несколько коммерческих и открытых инструментов также могут подключаться к Node.js Inspector.
Chrome DevTools 55+, Microsoft Edge
1. Откройте "chrome://inspect" в браузере на основе Chromium или "edge://inspect" в Edge. Нажмите кнопку "Configure" и убедитесь, что ваш целевой хост и порт указаны.
2. Скопируйте "devtoolsFrontendUrl" из вывода "/json/list" (см. выше) или текст подсказки "--inspect" и вставьте в Chrome.
Для получения дополнительной информации см. GitHub Chrome DevTools,
Microsoft Edge Insider.
Visual Studio Code 1.10+
В панели отладки нажмите на значок настроек, чтобы открыть ".vscode/launch.json". Выберите "Node.js" для начальной настройки.
Для получения дополнительной информации см. GitHub VSCode.
Visual Studio 2017+
Выберите "Debug > Start Debugging" в меню или нажмите "F5".
JetBrains WebStorm и другие IDE JetBrains
Создайте новую конфигурацию отладки Node.js и нажмите "Debug". "--inspect" будет использоваться по умолчанию для Node.js 7+. Чтобы отключить, снимите галочку "js.debugger.node.use.inspect" в реестре IDE. Для получения дополнительной информации о запуске и отладке Node.js в WebStorm и других IDE JetBrains см. WebStorm online help.
chrome-remote-interface
Библиотека для облегчения подключения к эндпоинтам Inspector Protocol.
Для получения дополнительной информации см. GitHub chrome-remote-interface.
Gitpod
Запустите конфигурацию отладки Node.js из представления Debug или нажмите "F5".
Для получения дополнительной информации см. Gitpod.
Eclipse IDE с расширением Eclipse Wild Web Developer
1. Из файла ".js" выберите "Debug As... > Node program", или
2. Создайте конфигурацию отладки для подключения отладчика к запущенному приложению Node.js (уже запущенному с "--inspect").
Для получения дополнительной информации см. Eclipse IDE.
Опции командной строки
Следующая таблица перечисляет влияние различных флагов времени выполнения на отладку:
| Флаг | Значение |
| "--inspect" | Включить агент инспектора; Слушать по умолчанию на адресе и порту (127.0.0.1:9229) |
| "--inspect=[host:port]" | Включить агент инспектора; Привязать к адресу или имени хоста "host" (по умолчанию: 127.0.0.1); Слушать на порту "port" (по умолчанию: 9229) |
| "--inspect-brk" | Включить агент инспектора; Слушать по умолчанию на адресе и порту (127.0.0.1:9229); Остановиться перед запуском пользовательского кода |
| "--inspect-brk=[host:port]" | Включить агент инспектора; Привязать к адресу или имени хоста "host" (по умолчанию: 127.0.0.1); Слушать на порту "port" (по умолчанию: 9229); Остановиться перед запуском пользовательского кода |
| "node inspect script.js" | Запустить дочерний процесс для выполнения скрипта пользователя с флагом "--inspect" и использовать основной процесс для запуска CLI отладчика |
| "node inspect --port=xxxx script.js" | Запустить дочерний процесс для выполнения скрипта пользователя с флагом "--inspect" и использовать основной процесс для запуска CLI отладчика. Слушать на порту "port" (по умолчанию: 9229) |
Включение удаленных сценариев отладки
Мы рекомендуем никогда не привязывать отладчик к публичному IP-адресу. Если вам нужно разрешить удалённые подключения для отладки, мы рекомендуем использовать SSH-туннели. Мы приводим следующий пример только для иллюстрации. Пожалуйста, поймите риск безопасности при разрешении удалённого доступа к привилегированной службе перед продолжением.
Предположим, вы запускаете Node.js на удалённой машине "remote.example.com", которую вы хотите отладить. На этой машине вы должны запустить процесс Node.js, слушая только локальный хост (по умолчанию):
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, на TCP-порту, по умолчанию 5858. Любой клиент отладки, который поддерживает этот протокол, может подключиться и отлаживать запущенный процесс; несколько популярных приведены ниже.
Протокол отладки V8 больше не поддерживается и не документирован.
Встроенный отладчик
Запустите "node debug script_name.js", чтобы запустить скрипт под встроенным командным отладчиком. Ваш скрипт запускается в другом процессе Node.js, запущенном с опцией "--debug-brk", а начальный процесс Node.js запускает скрипт "_debugger.js" и подключается к вашей цели. См. документацию для получения дополнительной информации.
node-inspector
Отлаживайте ваше приложение Node.js с помощью Chrome DevTools, используя промежуточный процесс, который переводит протокол Inspector, используемый в Chromium, в протокол отладки V8, используемый в Node.js. См. node-inspector для получения дополнительной информации.