Depuración de Node.js
Esta guía te ayudará a empezar a depurar tus aplicaciones y scripts de Node.js.
Habilitar Inspector
Cuando se inicia con el modificador --inspect, un proceso de Node.js escucha a un cliente de depuración. Por defecto, escuchará en el host y puerto 127.0.0.1:9229. A cada proceso también se le asigna un UUID único.
Los clientes de Inspector deben conocer y especificar la dirección del host, el puerto y el UUID para conectarse. Una URL completa tendrá un aspecto similar a ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.
Node.js también comenzará a escuchar mensajes de depuración si recibe una señal SIGUSR1. (La señal SIGUSR1 no está disponible en Windows). En Node.js 7 y versiones anteriores, esto activa la API de depuración heredada. En Node.js 8 y versiones posteriores, activará la API de Inspector.
Implicaciones de seguridad
Dado que el depurador tiene acceso completo al entorno de ejecución de Node.js, un actor malicioso capaz de conectarse a este puerto puede ejecutar código arbitrario en nombre del proceso de Node.js. Es importante comprender las implicaciones de seguridad de exponer el puerto del depurador en redes públicas y privadas.
Exponer el puerto de depuración públicamente no es seguro
Si el depurador está vinculado a una dirección IP pública, o a 0.0.0.0, cualquier cliente que pueda alcanzar su dirección IP podrá conectarse al depurador sin ninguna restricción y podrá ejecutar código arbitrario.
Por defecto, node --inspect se vincula a 127.0.0.1. Necesita proporcionar explícitamente una dirección IP pública o 0.0.0.0, etc., si pretende permitir conexiones externas al depurador. Hacerlo puede exponerle a una amenaza de seguridad potencialmente significativa. Le sugerimos que se asegure de que existen firewalls y controles de acceso adecuados para evitar una exposición a la seguridad.
Consulte la sección sobre "Habilitación de escenarios de depuración remota" para obtener algunos consejos sobre cómo permitir de forma segura que los clientes de depuración remota se conecten.
Las aplicaciones locales tienen acceso completo al inspector
Incluso si vincula el puerto del inspector a 127.0.0.1 (el valor predeterminado), cualquier aplicación que se ejecute localmente en su máquina tendrá acceso sin restricciones. Esto es por diseño para permitir que los depuradores locales puedan adjuntarse cómodamente.
Navegadores, WebSockets y política del mismo origen
Los sitios web que se abren en un navegador web pueden realizar solicitudes WebSocket y HTTP bajo el modelo de seguridad del navegador. Es necesaria una conexión HTTP inicial para obtener un ID de sesión de depuración único. La política del mismo origen impide que los sitios web puedan realizar esta conexión HTTP. Para mayor seguridad contra ataques de redireccionamiento DNS, Node.js verifica que los encabezados 'Host' para la conexión especifiquen una dirección IP o localhost precisamente.
Estas políticas de seguridad impiden la conexión a un servidor de depuración remoto especificando el nombre de host. Puede evitar esta restricción especificando la dirección IP o utilizando túneles ssh como se describe a continuación.
Clientes del Inspector
Hay un depurador CLI mínimo disponible con node inspect myscript.js. Varias herramientas comerciales y de código abierto también pueden conectarse al Inspector de Node.js.
Chrome DevTools 55+, Microsoft Edge
- Opción 1: Abra
chrome://inspecten un navegador basado en Chromium oedge://inspecten Edge. Haga clic en el botón Configurar y asegúrese de que su host y puerto de destino estén en la lista. - Opción 2: Copie
devtoolsFrontendUrlde la salida de/json/list(ver arriba) o del texto de sugerencia--inspecty péguelo en Chrome.
Consulte https://github.com/ChromeDevTools/devtools-frontend, https://www.microsoftedgeinsider.com para obtener más información.
Visual Studio Code 1.10+
- En el panel de Depuración, haga clic en el icono de configuración para abrir
.vscode/launch.json. Seleccione "Node.js" para la configuración inicial.
Consulte https://github.com/microsoft/vscode para obtener más información.
JetBrains WebStorm y otros IDE de JetBrains
- Cree una nueva configuración de depuración de Node.js y pulse Depurar.
--inspectse utilizará de forma predeterminada para Node.js 7+. Para desactivarlo, desmarquejs.debugger.node.use.inspecten el Registro del IDE. Para obtener más información sobre cómo ejecutar y depurar Node.js en WebStorm y otros IDE de JetBrains, consulte la ayuda en línea de WebStorm.
chrome-remote-interface
- Biblioteca para facilitar las conexiones a los puntos finales del Protocolo de Inspector. Consulte https://github.com/cyrus-and/chrome-remote-interface para obtener más información.
Gitpod
- Inicie una configuración de depuración de Node.js desde la vista
Depuraro pulseF5. Instrucciones detalladas
Consulte https://www.gitpod.io para obtener más información.
Eclipse IDE con la extensión Eclipse Wild Web Developer
- Desde un archivo
.js, eligeDepurar como... > Programa de Node, o Crea una Configuración de Depuración para adjuntar el depurador a la aplicación Node.js en ejecución (ya iniciada con--inspect).
Consulta https://eclipse.org/eclipseide para obtener más información.
Opciones de línea de comandos
La siguiente tabla enumera el impacto de varias flags de tiempo de ejecución en la depuración:
| Flag | Significado |
|---|---|
--inspect | Habilita la depuración con el Inspector de Node.js. Escucha en la dirección y el puerto predeterminados (127.0.0.1:9229) |
--inspect-brk | Habilita la depuración con el Inspector de Node.js. Escucha en la dirección y el puerto predeterminados (127.0.0.1:9229); Detiene la ejecución antes de que comience el código del usuario |
--inspect=[host:port] | Habilita el agente del inspector; Se enlaza a la dirección o nombre de host host (predeterminado: 127.0.0.1); Escucha en el puerto port (predeterminado: 9229) |
--inspect-brk=[host:port] | Habilita el agente del inspector; Se enlaza a la dirección o nombre de host host (predeterminado: 127.0.0.1); Escucha en el puerto port (predeterminado: 9229); Detiene la ejecución antes de que comience el código del usuario |
--inspect-wait | Habilita el agente del inspector; Escucha en la dirección y el puerto predeterminados (127.0.0.1:9229); Espera a que se adjunte el depurador. |
--inspect-wait=[host:port] | Habilita el agente del inspector; Se enlaza a la dirección o nombre de host host (predeterminado: 127.0.0.1); Escucha en el puerto port (predeterminado: 9229); Espera a que se adjunte el depurador. |
node inspect script.js | Crea un proceso hijo para ejecutar el script del usuario con la flag --inspect; y usa el proceso principal para ejecutar el depurador CLI. |
node inspect --port=xxxx script.js | Crea un proceso hijo para ejecutar el script del usuario con la flag --inspect; y usa el proceso principal para ejecutar el depurador CLI. Escucha en el puerto port (predeterminado: 9229) |
Habilitación de escenarios de depuración remota
Recomendamos que nunca haga que el depurador escuche en una dirección IP pública. Si necesita permitir conexiones de depuración remota, recomendamos el uso de túneles ssh en su lugar. Proporcionamos el siguiente ejemplo solo con fines ilustrativos. Por favor, comprenda el riesgo de seguridad de permitir el acceso remoto a un servicio privilegiado antes de proceder.
Digamos que está ejecutando Node.js en una máquina remota, remote.example.com, que desea poder depurar. En esa máquina, debe iniciar el proceso de nodo con el inspector escuchando solo en localhost (el valor predeterminado).
node --inspect app.jsAhora, en su máquina local desde donde desea iniciar una conexión de cliente de depuración, puede configurar un túnel ssh:
ssh -L 9225:localhost:9229 remote.example.comEsto inicia una sesión de túnel ssh donde una conexión al puerto 9221 en su máquina local se reenviará al puerto 9229 en remote.example.com. Ahora puede adjuntar un depurador como Chrome DevTools o Visual Studio Code a localhost:9221, que debería poder depurar como si la aplicación Node.js se estuviera ejecutando localmente.
Depurador Legacy
El depurador legacy ha quedado obsoleto a partir de Node.js 7.7.0. Por favor, use --inspect e Inspector en su lugar.
Cuando se inicia con los modificadores --debug o --debug-brk en la versión 7 y anteriores, Node.js escucha los comandos de depuración definidos por el Protocolo de Depuración V8 descontinuado en un puerto TCP, por defecto 5858. Cualquier cliente de depuración que hable este protocolo puede conectarse y depurar el proceso en ejecución; un par de los más populares se enumeran a continuación.
El Protocolo de Depuración V8 ya no se mantiene ni se documenta.
Depurador Integrado
Inicie node debug script_name.js para iniciar su script bajo el depurador de línea de comandos integrado. Su script se inicia en otro proceso de Node.js iniciado con la opción --debug-brk, y el proceso inicial de Node.js ejecuta el script _debugger.js y se conecta a su destino. Consulte docs para obtener más información.
node-inspector
Depure su aplicación Node.js con Chrome DevTools utilizando un proceso intermedio que traduce el Protocolo Inspector utilizado en Chromium al protocolo de Depuración V8 utilizado en Node.js. Consulte https://github.com/node-inspector/node-inspector para obtener más información.