Отладка Node.js
Это руководство поможет вам начать отладку ваших приложений и скриптов 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-соединение. Политика одного источника (same-origin-policy) предотвращает возможность веб-сайтов устанавливать это HTTP-соединение. Для дополнительной защиты от атак DNS-ребиндинга Node.js проверяет, указывают ли заголовки 'Host' для соединения точно IP-адрес или localhost.
Эти политики безопасности запрещают подключение к удалённому серверу отладки путём указания имени хоста. Вы можете обойти это ограничение, указав либо IP-адрес, либо используя SSH-туннели, как описано ниже.
Клиенты инспектора
Минимальный отладчик командной строки доступен с помощью node inspect myscript.js. Несколько коммерческих и open-source инструментов также могут подключаться к Node.js Inspector.
Chrome DevTools 55+, Microsoft Edge
- Вариант 1: Откройте
chrome://inspectв браузере на основе Chromium илиedge://inspectв Edge. Нажмите кнопку «Настроить» и убедитесь, что указаны ваш целевой хост и порт. - Вариант 2: Скопируйте
devtoolsFrontendUrlиз вывода/json/list(см. выше) или подсказку--inspectи вставьте в Chrome.
См. https://github.com/ChromeDevTools/devtools-frontend, https://www.microsoftedgeinsider.com для получения дополнительной информации.
Visual Studio Code 1.10+
- В панели отладки нажмите значок настроек, чтобы открыть
.vscode/launch.json. Выберите "Node.js" для начальной настройки.
См. https://github.com/microsoft/vscode для получения дополнительной информации.
JetBrains WebStorm и другие IDE JetBrains
- Создайте новую конфигурацию отладки Node.js и нажмите «Отладка».
--inspectбудет использоваться по умолчанию для Node.js 7+. Чтобы отключить, снимите флажокjs.debugger.node.use.inspectв реестре IDE. Чтобы узнать больше о запуске и отладке Node.js в WebStorm и других IDE JetBrains, ознакомьтесь со справкой WebStorm онлайн.
chrome-remote-interface
- Библиотека для упрощения подключения к конечным точкам Inspector Protocol. См. https://github.com/cyrus-and/chrome-remote-interface для получения дополнительной информации.
Gitpod
- Запустите конфигурацию отладки Node.js из представления «Отладка» или нажмите
F5. Подробные инструкции
См. https://www.gitpod.io для получения дополнительной информации.
Eclipse IDE с расширением Eclipse Wild Web Developer
- Из файла
.jsвыберитеОтладить как... > Программа Node, или создайте конфигурацию отладки для подключения отладчика к запущенному приложению Node.js (уже запущенному с--inspect).
См. https://eclipse.org/eclipseide для получения дополнительной информации.
Параметры командной строки
В следующей таблице перечислены последствия различных флагов времени выполнения для отладки:
| Флаг | Описание |
|---|---|
--inspect | Включить отладку с помощью Node.js Inspector. Слушать по адресу и порту по умолчанию (127.0.0.1:9229) |
--inspect-brk | Включить отладку с помощью Node.js Inspector. Слушать по адресу и порту по умолчанию (127.0.0.1:9229); Прервать выполнение до начала пользовательского кода |
--inspect=[host:port] | Включить агент инспектора; Привязать к адресу или имени хоста host (по умолчанию: 127.0.0.1); Слушать на порту port (по умолчанию: 9229) |
--inspect-brk=[host:port] | Включить агент инспектора; Привязать к адресу или имени хоста host (по умолчанию: 127.0.0.1); Слушать на порту port (по умолчанию: 9229); Прервать выполнение до начала пользовательского кода |
--inspect-wait | Включить агент инспектора; Слушать по адресу и порту по умолчанию (127.0.0.1:9229); Ожидать подключения отладчика. |
--inspect-wait=[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 с инспектором, прослушивающим только localhost (по умолчанию).
node --inspect app.jsТеперь, на вашей локальной машине, с которой вы хотите установить соединение клиента отладки, вы можете настроить SSH-туннель:
ssh -L 9225:localhost:9229 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, используя промежуточный процесс, который переводит протокол инспектора , используемый в Chromium, в протокол отладчика V8, используемый в Node.js. Более подробную информацию см. на странице https://github.com/node-inspector/node-inspector.