Отладка

В этой документации объясняется, как можно отлаживать фронтенд и бэкенд код Next.js с полной поддержкой карт источников (source maps), используя либо отладчик VS Code, либо Chrome DevTools.

Любой отладчик, который может подключаться к Node.js, также может использоваться для отладки приложения Next.js. Подробнее об этом можно узнать в Руководстве по отладке Node.js.

Отладка в VS Code

Создайте файл .vscode/launch.json в корне вашего проекта со следующим содержимым:

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 можно заменить на yarn dev, если вы используете Yarn. Если вы изменяете номер порта, на котором запускается ваше приложение, замените 3000 в http://localhost:3000 на используемый вами порт.

Теперь перейдите в панель Debug (Ctrl+Shift+D на Windows/Linux, ⇧+⌘+D на macOS), выберите конфигурацию запуска и нажмите F5 или выберите Debug: Start Debugging в Command Palette, чтобы начать сеанс отладки.

Использование отладчика в Jetbrains WebStorm

Нажмите на выпадающее меню с перечнем конфигураций запуска и выберите Edit Configurations.... Создайте конфигурацию отладки Javascript Debug с URL http://localhost:3000. Настройте по своему усмотрению (например, браузер для отладки, сохранение как файла проекта) и нажмите OK. Запустите эту конфигурацию отладки, и выбранный браузер должен автоматически открыться. На этом этапе у вас должно быть 2 приложения в режиме отладки: NextJS node-приложение и клиентское/браузерное приложение.

Отладка с помощью Chrome DevTools

Клиентский код

Запустите сервер разработки как обычно, выполнив next dev, npm run dev или yarn dev. После запуска сервера откройте http://localhost:3000 (или ваш альтернативный URL) в Chrome. Затем откройте Chrome Developer Tools (Ctrl+Shift+J на Windows/Linux, ⌥+⌘+I на macOS) и перейдите на вкладку Sources.

Теперь, когда ваш клиентский код достигнет оператора debugger, выполнение кода приостановится, и этот файл появится в области отладки. Вы также можете нажать Ctrl+P на Windows/Linux или ⌘+P на macOS для поиска файла и установки точек останова вручную. Обратите внимание, что при поиске ваши исходные файлы будут иметь пути, начинающиеся с webpack://_N_E/./.

Серверный код

Для отладки серверного кода Next.js с помощью Chrome DevTools необходимо передать флаг --inspect в процесс Node.js:

Terminal

NODE_OPTIONS='--inspect' next dev

Если вы используете npm run dev или yarn dev, обновите скрипт dev в вашем package.json:

package.json

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

Запуск сервера разработки Next.js с флагом --inspect будет выглядеть примерно так:

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

Обратите внимание, что выполнение NODE_OPTIONS='--inspect' npm run dev или NODE_OPTIONS='--inspect' yarn dev не сработает. Это попытается запустить несколько отладчиков на одном порту: один для процесса npm/yarn и один для Next.js. В результате в консоли появится ошибка вида Starting inspector on 127.0.0.1:9229 failed: address already in use.

После запуска сервера откройте новую вкладку в Chrome и перейдите по адресу chrome://inspect, где вы должны увидеть ваше приложение Next.js в разделе Remote Target. Нажмите inspect под вашим приложением, чтобы открыть отдельное окно DevTools, затем перейдите на вкладку Sources.

Отладка серверного кода здесь работает аналогично отладке клиентского кода с помощью Chrome DevTools, за исключением того, что при поиске файлов с помощью Ctrl+P или ⌘+P ваши исходные файлы будут иметь пути, начинающиеся с webpack://{application-name}/./ (где {application-name} будет заменено на имя вашего приложения согласно файлу package.json).

Отладка на Windows

Пользователи Windows могут столкнуться с проблемой при использовании NODE_OPTIONS='--inspect', так как этот синтаксис не поддерживается на платформах Windows. Чтобы обойти это, установите пакет cross-env как зависимость разработки (-D для npm и yarn) и замените скрипт dev следующим:

package.json

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

cross-env установит переменную окружения NODE_OPTIONS независимо от платформы (включая Mac, Linux и Windows) и позволит вам отлаживать код единообразно на всех устройствах и операционных системах.

Полезно знать: Убедитесь, что Windows Defender отключен на вашем компьютере. Эта внешняя служба проверяет каждый читаемый файл, что, как сообщается, значительно увеличивает время Fast Refresh при использовании next dev. Это известная проблема, не связанная напрямую с Next.js, но она влияет на разработку в Next.js.

Дополнительная информация

Чтобы узнать больше об использовании отладчика JavaScript, ознакомьтесь со следующей документацией: