Depuración

Esta documentación explica cómo puede depurar el código frontend y backend de su aplicación Next.js con soporte completo de mapas de origen, utilizando el depurador de VS Code o Chrome DevTools.

Cualquier depurador que pueda conectarse a Node.js también puede usarse para depurar una aplicación Next.js. Puede encontrar más detalles en la Guía de depuración de Node.js.

Depuración con VS Code

Cree un archivo llamado .vscode/launch.json en la raíz de su proyecto con el siguiente contenido:

launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: depuración del lado del servidor",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: depuración del lado del cliente",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: depuración completa",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

npm run dev puede reemplazarse con yarn dev si está usando Yarn. Si está cambiando el número de puerto en el que inicia su aplicación, reemplace el 3000 en http://localhost:3000 con el puerto que esté utilizando.

Ahora vaya al panel de Depuración (Ctrl+Shift+D en Windows/Linux, ⇧+⌘+D en macOS), seleccione una configuración de inicio y presione F5 o seleccione Depurar: Iniciar depuración desde la Paleta de comandos para comenzar su sesión de depuración.

Uso del depurador en Jetbrains WebStorm

Haga clic en el menú desplegable que lista la configuración de tiempo de ejecución y seleccione Editar configuraciones.... Cree una configuración de depuración Javascript Debug con http://localhost:3000 como URL. Personalícelo a su gusto (por ejemplo, navegador para depuración, guardar como archivo de proyecto) y haga clic en OK. Ejecute esta configuración de depuración y el navegador seleccionado debería abrirse automáticamente. En este punto, debería tener 2 aplicaciones en modo de depuración: la aplicación node de NextJS y la aplicación cliente/navegador.

Depuración con Chrome DevTools

Código del lado del cliente

Inicie su servidor de desarrollo como de costumbre ejecutando next dev, npm run dev o yarn dev. Una vez que el servidor se inicie, abra http://localhost:3000 (o su URL alternativa) en Chrome. A continuación, abra las Herramientas para desarrolladores de Chrome (Ctrl+Shift+J en Windows/Linux, ⌥+⌘+I en macOS) y vaya a la pestaña Sources.

Ahora, cada vez que su código del lado del cliente alcance una declaración debugger, la ejecución del código se pausará y ese archivo aparecerá en el área de depuración. También puede presionar Ctrl+P en Windows/Linux o ⌘+P en macOS para buscar un archivo y establecer puntos de interrupción manualmente. Tenga en cuenta que al buscar aquí, sus archivos fuente tendrán rutas que comienzan con webpack://_N_E/./.

Código del lado del servidor

Para depurar código de Next.js del lado del servidor con Chrome DevTools, necesita pasar la bandera --inspect al proceso subyacente de Node.js:

Terminal

NODE_OPTIONS='--inspect' next dev

Si está usando npm run dev o yarn dev, entonces debe actualizar el script dev en su package.json:

package.json

{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next dev"
  }
}

Iniciar el servidor de desarrollo de Next.js con la bandera --inspect se verá algo así:

Terminal

Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Tenga en cuenta que ejecutar NODE_OPTIONS='--inspect' npm run dev o NODE_OPTIONS='--inspect' yarn dev no funcionará. Esto intentaría iniciar múltiples depuradores en el mismo puerto: uno para el proceso npm/yarn y otro para Next.js. Entonces obtendría un error como Starting inspector on 127.0.0.1:9229 failed: address already in use en su consola.

Una vez que el servidor se inicie, abra una nueva pestaña en Chrome y visite chrome://inspect, donde debería ver su aplicación Next.js dentro de la sección Remote Target. Haga clic en inspect debajo de su aplicación para abrir una ventana separada de DevTools, luego vaya a la pestaña Sources.

La depuración del código del lado del servidor aquí funciona de manera similar a la depuración del código del lado del cliente con Chrome DevTools, excepto que cuando busca archivos aquí con Ctrl+P o ⌘+P, sus archivos fuente tendrán rutas que comienzan con webpack://{nombre-de-la-aplicación}/./ (donde {nombre-de-la-aplicación} se reemplazará con el nombre de su aplicación según su archivo package.json).

Depuración en Windows

Los usuarios de Windows pueden encontrar un problema al usar NODE_OPTIONS='--inspect' ya que esa sintaxis no es compatible con plataformas Windows. Para solucionar esto, instale el paquete cross-env como dependencia de desarrollo (-D con npm y yarn) y reemplace el script dev con lo siguiente.

package.json

{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS='--inspect' next dev"
  }
}

cross-env establecerá la variable de entorno NODE_OPTIONS independientemente de la plataforma en la que se encuentre (incluidos Mac, Linux y Windows) y le permitirá depurar de manera consistente en todos los dispositivos y sistemas operativos.

Bueno saber: Asegúrese de que Windows Defender esté desactivado en su máquina. Este servicio externo verificará cada archivo leído, lo que según informes aumenta considerablemente el tiempo de Fast Refresh con next dev. Este es un problema conocido, no relacionado con Next.js, pero sí afecta el desarrollo con Next.js.

Más información

Para aprender más sobre cómo usar un depurador de JavaScript, consulte la siguiente documentación: