Depuración

Esta documentación explica cómo puede depurar el código del 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: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "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 o pnpm dev si está usando pnpm.

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é usando.

Si está ejecutando Next.js desde un directorio diferente a la raíz (por ejemplo, si está usando Turborepo), entonces necesita agregar cwd a las tareas de depuración del lado del servidor y de pila completa. Por ejemplo, "cwd": "${workspaceFolder}/apps/web".

Ahora vaya al panel de Depuración (Ctrl+Shift+D en Windows/Linux, ⇧+⌘+D en macOS), seleccione una configuración de lanzamiento, luego presione F5 o seleccione Debug: Start Debugging desde la Paleta de Comandos para iniciar su sesión de depuración.

Usando el depurador en Jetbrains WebStorm

Haga clic en el menú desplegable que lista la configuración de tiempo de ejecución y haga clic en Edit Configurations.... Cree una configuración de depuración Javascript Debug con http://localhost:3000 como la URL. Personalice 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 del 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 inicie, abra http://localhost:3000 (o su URL alternativa) en Chrome. Luego, abra las Herramientas de Desarrollo 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 del lado del servidor de Next.js 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 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.

Depurar código del lado del servidor aquí funciona de manera similar a depurar 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://{application-name}/./ (donde {application-name} será reemplazado 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 esté (incluyendo Mac, Linux y Windows) y le permitirá depurar de manera consistente entre 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: