Отладка 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 и более ранних версиях это активирует устаревший 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 и т. д., если вы хотите разрешить внешние подключения к отладчику. Это может подвергнуть вас потенциально значительной угрозе безопасности. Мы рекомендуем вам убедиться, что установлены соответствующие брандмауэры и средства контроля доступа для предотвращения угрозы безопасности.
См. раздел 'Включение сценариев удаленной отладки' с советами о том, как безопасно разрешить удаленным отладочным клиентам подключаться.
Локальные приложения имеют полный доступ к инспектору
Даже если вы привяжете порт инспектора к 127.0.0.1 (по умолчанию), любые приложения, работающие локально на вашем компьютере, будут иметь неограниченный доступ. Это сделано для того, чтобы локальные отладчики могли удобно подключаться.
Браузеры, WebSockets и политика одного источника
Веб-сайты, открытые в веб-браузере, могут выполнять WebSocket и HTTP-запросы в соответствии с моделью безопасности браузера. Начальное HTTP-соединение необходимо для получения уникального идентификатора сеанса отладки. Политика одного источника не позволяет веб-сайтам устанавливать это HTTP-соединение. Для дополнительной защиты от атак с перепривязкой DNS, Node.js проверяет, что заголовки 'Host' для соединения точно указывают IP-адрес или localhost.
Эти политики безопасности запрещают подключение к удаленному серверу отладки путем указания имени хоста. Вы можете обойти это ограничение, указав IP-адрес или используя SSH-туннели, как описано ниже.
Клиенты Inspector
Минимальный отладчик 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.
См. https://github.com/ChromeDevTools/devtools-frontend, https://www.microsoftedgeinsider.com для получения дополнительной информации.
Visual Studio Code 1.10+
- На панели Debug щелкните значок настроек, чтобы открыть
.vscode/launch.json. Выберите "Node.js" для первоначальной настройки.
См. https://github.com/microsoft/vscode для получения дополнительной информации.
JetBrains WebStorm и другие IDE JetBrains
- Создайте новую конфигурацию отладки Node.js и нажмите Debug.
--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 из представления
Debugили нажмитеF5. Подробные инструкции
Дополнительную информацию см. на https://www.gitpod.io.
Eclipse IDE с расширением Eclipse Wild Web Developer
- Из файла
.jsвыберитеDebug As... > Node programили Создайте конфигурацию отладки для подключения отладчика к работающему приложению 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] | Включить агент inspector; Привязаться к адресу или имени хоста host (по умолчанию: 127.0.0.1); Прослушивать порт port (по умолчанию: 9229) |
--inspect-brk=[host:port] | Включить агент inspector; Привязаться к адресу или имени хоста host (по умолчанию: 127.0.0.1); Прослушивать порт port (по умолчанию: 9229); Остановить перед началом пользовательского кода |
--inspect-wait | Включить агент inspector; Прослушивать адрес и порт по умолчанию (127.0.0.1:9229); Ожидать подключения отладчика. |
--inspect-wait=[host:port] | Включить агент inspector; Привязаться к адресу или имени хоста 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, используя промежуточный процесс, который переводит Inspector Protocol, используемый в Chromium, в протокол V8 Debugger, используемый в Node.js. Подробности см. на https://github.com/node-inspector/node-inspector.