logoNext.js Русский
ДокументацияБлогИзучение
Введение/Руководства/Отладка

Использование инструментов отладки с Next.js

В этой документации объясняется, как вы можете отлаживать фронтенд и бэкенд код вашего Next.js приложения с полной поддержкой карт источников (source maps), используя отладчик VS Code, Chrome DevTools или Firefox 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 client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

Примечание: Для использования отладки Firefox в VS Code необходимо установить расширение Firefox Debugger.

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

В конфигурации "Next.js: debug full stack" параметр serverReadyAction.action определяет, какой браузер открывать при готовности сервера. Значение debugWithEdge означает запуск браузера Edge. Если вы используете Chrome, измените это значение на debugWithChrome.

Если вы изменяете номер порта, на котором запускается ваше приложение, замените 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 и клиентское/браузерное приложение.

Отладка с помощью браузерных DevTools

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

Запустите сервер разработки как обычно, выполнив next dev, npm run dev или yarn dev. После запуска сервера откройте http://localhost:3000 (или ваш альтернативный URL) в предпочитаемом браузере.

Для Chrome:

  • Откройте Инструменты разработчика Chrome (Ctrl+Shift+J в Windows/Linux, ⌥+⌘+I в macOS)
  • Перейдите на вкладку Sources

Для Firefox:

  • Откройте Инструменты разработчика Firefox (Ctrl+Shift+I в Windows/Linux, ⌥+⌘+I в macOS)
  • Перейдите на вкладку Debugger

В любом браузере, когда ваш клиентский код достигнет оператора debugger, выполнение кода приостановится, и этот файл появится в области отладки. Вы также можете искать файлы для установки точек останова вручную:

  • В Chrome: Нажмите Ctrl+P в Windows/Linux или ⌘+P в macOS
  • В Firefox: Нажмите Ctrl+P в Windows/Linux или ⌘+P в macOS или используйте дерево файлов на левой панели

Обратите внимание, что при поиске пути к вашим исходным файлам будут начинаться с webpack://_N_E/./.

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

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

Terminal
NODE_OPTIONS='--inspect' next dev

Полезно знать: Используйте NODE_OPTIONS='--inspect=0.0.0.0', чтобы разрешить удаленный доступ для отладки за пределами localhost, например, при запуске приложения в контейнере Docker.

Если вы используете 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

Для Chrome:

  1. Откройте новую вкладку и перейдите по адресу chrome://inspect
  2. Нажмите Configure..., чтобы убедиться, что оба порта отладки указаны
  3. Добавьте localhost:9229 и localhost:9230, если их еще нет
  4. Найдите ваше приложение Next.js в разделе Remote Target
  5. Нажмите inspect, чтобы открыть отдельное окно DevTools
  6. Перейдите на вкладку Sources

Для Firefox:

  1. Откройте новую вкладку и перейдите по адресу about:debugging
  2. Нажмите This Firefox в левой боковой панели
  3. В разделе Remote Targets найдите ваше приложение Next.js
  4. Нажмите Inspect, чтобы открыть отладчик
  5. Перейдите на вкладку Debugger

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

Инспектирование серверных ошибок с помощью браузерных DevTools

При возникновении ошибки инспектирование исходного кода может помочь отследить ее первопричину.

Next.js отобразит значок Node.js под индикатором версии Next.js на оверлее ошибки. Нажав на этот значок, вы скопируете URL DevTools в буфер обмена. Вы можете открыть новую вкладку браузера с этим URL для инспектирования процесса сервера Next.js.

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

Пользовательский сервер

Запуск приложения Next.js программно с использованием пользовательского сервера.

Draft Mode

Next.js предоставляет режим черновика (Draft Mode) для переключения между статическими и динамическими страницами. Здесь вы узнаете, как это работает с App Router.