Отладка

Эта документация объясняет, как можно отлаживать фронтенд и бэкенд код 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: отладка серверной части",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: отладка клиентской части",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: полная отладка стека",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

npm run dev можно заменить на yarn dev, если вы используете Yarn, или pnpm dev для pnpm.

Если вы изменяете номер порта, на котором запускается приложение, замените 3000 в http://localhost:3000 на используемый вами порт.

Если вы запускаете Next.js из каталога, отличного от корневого (например, при использовании Turborepo), добавьте параметр cwd в задачи отладки серверной части и полного стека. Например: "cwd": "${workspaceFolder}/apps/web".

Перейдите в панель 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 приложения в режиме отладки: Node-приложение NextJS и клиентское/браузерное приложение.

Отладка с помощью 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, ознакомьтесь со следующей документацией: