CLI Next.js (next)

CLI Next.js позволяет разрабатывать, собирать, запускать ваше приложение и многое другое.

Основное использование:

Терминал

npm run next [команда] [опции]

Справочник

Доступны следующие опции:

Опции	Описание
`-h` или `--help`	Показывает все доступные опции
`-v` или `--version`	Выводит номер версии Next.js

Команды

Доступны следующие команды:

Команда	Описание
`dev`	Запускает Next.js в режиме разработки с Hot Module Reloading, отчётом об ошибках и другими функциями.
`build`	Создаёт оптимизированную production-сборку вашего приложения. Отображает информацию о каждом маршруте.
`start`	Запускает Next.js в production-режиме. Приложение должно быть предварительно собрано с помощью `next build`.
`info`	Выводит актуальные сведения о текущей системе, которые можно использовать для сообщения об ошибках в Next.js.
`lint`	Запускает ESLint для всех файлов в директориях `/src`, `/app`, `/pages`, `/components` и `/lib`. Также предоставляет пошаговую настройку для установки необходимых зависимостей, если ESLint ещё не настроен в вашем приложении.
`telemetry`	Позволяет включить или отключить полностью анонимный сбор телеметрии в Next.js.

Полезно знать: Запуск next без команды является алиасом для next dev.

Опции `next dev`

next dev запускает приложение в режиме разработки с Hot Module Reloading (HMR), отчётом об ошибках и другими функциями. При запуске next dev доступны следующие опции:

Опция	Описание
`-h, --help`	Показать все доступные опции.
`[directory]`	Директория для сборки приложения. Если не указана, используется текущая директория.
`--turbo`	Запускает режим разработки с использованием Turbopack.
`-p` или `--port <port>`	Указывает номер порта для запуска приложения. По умолчанию: 3000, переменная окружения: PORT
`-H`или `--hostname <hostname>`	Указывает имя хоста для запуска приложения. Полезно для доступа к приложению с других устройств в сети. По умолчанию: 0.0.0.0
`--experimental-https`	Запускает сервер с HTTPS и генерирует самоподписанный сертификат.
`--experimental-https-key <path>`	Путь к файлу ключа HTTPS.
`--experimental-https-cert <path>`	Путь к файлу сертификата HTTPS.
`--experimental-https-ca <path>`	Путь к файлу центра сертификации HTTPS.
`--experimental-upload-trace <traceUrl>`	Отправляет подмножество отладочной трассировки на удалённый HTTP-URL.

Опции `next build`

next build создаёт оптимизированную production-сборку вашего приложения. В выводе отображается информация о каждом маршруте. Например:

Терминал

Маршрут (app)                              Размер     Первая загрузка JS
┌ ○ /_not-found                          0 B               0 kB
└ ƒ /products/[id]                       0 B               0 kB

○  (Статический)   предварительно отрендерен как статический контент
ƒ  (Динамический)  рендерится на сервере по запросу

Размер: Размер ресурсов, загружаемых при навигации на страницу на стороне клиента. Размер для каждого маршрута включает только его зависимости.
Первая загрузка JS: Размер ресурсов, загружаемых при посещении страницы с сервера. Объём JS, общего для всех, показан как отдельный показатель.

Оба этих значения сжаты с помощью gzip. Первая загрузка обозначается зелёным, жёлтым или красным цветом. Стремитесь к зелёному для производительных приложений.

Для команды next build доступны следующие опции:

Опция	Описание
`-h, --help`	Показать все доступные опции.
`[directory]`	Директория для сборки приложения. Если не указана, используется текущая директория.
`-d` или `--debug`	Включает более подробный вывод сборки. С этим флагом будут показаны дополнительные данные, такие как редиректы, перезаписи и заголовки.

`--profile`	Включает профилирование для React в production.
`--no-lint`	Отключает линтинг.
`--no-mangling`	Отключает искажение имён. Это может повлиять на производительность и должно использоваться только для отладки.
`--experimental-app-only`	Собирает только маршруты App Router.
`--experimental-build-mode [mode]`	Использует экспериментальный режим сборки. (варианты: "compile", "generate", по умолчанию: "default")

Опции `next start`

next start запускает приложение в production-режиме. Приложение должно быть предварительно собрано с помощью next build.

Для команды next start доступны следующие опции:

Опция	Описание
`-h` или `--help`	Показать все доступные опции.
`[directory]`	Директория для запуска приложения. Если не указана, используется текущая директория.
`-p` или `--port <port>`	Указывает номер порта для запуска приложения. (по умолчанию: 3000, переменная окружения: PORT)
`-H` или `--hostname <hostname>`	Указывает имя хоста для запуска приложения (по умолчанию: 0.0.0.0).
`--keepAliveTimeout <keepAliveTimeout>`	Указывает максимальное количество миллисекунд ожидания перед закрытием неактивных соединений.

next info выводит актуальные сведения о текущей системе, которые можно использовать для сообщения об ошибках в Next.js при создании issue на GitHub. Эта информация включает платформу/архитектуру/версию операционной системы, бинарные файлы (Node.js, npm, Yarn, pnpm), версии пакетов (next, react, react-dom) и другое.

Вывод должен выглядеть так:

Терминал

Операционная система:
  Платформа: darwin
  Архитектура: arm64
  Версия: Darwin Kernel Version 23.6.0
  Доступная память (МБ): 65536
  Доступные ядра CPU: 10
Бинарные файлы:
  Node: 20.12.0
  npm: 10.5.0
  Yarn: 1.22.19
  pnpm: 9.6.0
Актуальные пакеты:
  next: 15.0.0-canary.115 // Определена последняя доступная версия (15.0.0-canary.115).
  eslint-config-next: 14.2.5
  react: 19.0.0-rc
  react-dom: 19.0.0
  typescript: 5.5.4
Конфигурация Next.js:
  output: N/A

Для команды next info доступны следующие опции:

Опция	Описание
`-h` или `--help`	Показать все доступные опции
`--verbose`	Собирает дополнительную информацию для отладки.

Опции `next lint`

next lint запускает ESLint для всех файлов в директориях pages/, app/, components/, lib/ и src/. Также предоставляет пошаговую настройку для установки необходимых зависимостей, если ESLint ещё не настроен в вашем приложении.

Для команды next lint доступны следующие опции:

Опция	Описание
`[directory]`	Базовая директория для линтинга приложения. Если не указана, используется текущая директория.
`-d, --dir, <dirs...>`	Включает директорию или директории для запуска ESLint.
`--file, <files...>`	Включает файл или файлы для запуска ESLint.
`--ext, [exts...]`	Указывает расширения JavaScript-файлов. (по умолчанию: [".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"])
`-c, --config, <config>`	Использует этот файл конфигурации, переопределяя все другие параметры конфигурации.
`--resolve-plugins-relative-to, <rprt>`	Указывает директорию, из которой должны разрешаться плагины.
`--strict`	Создаёт файл `.eslintrc.json` с использованием строгой конфигурации Next.js.
`--rulesdir, <rulesdir...>`	Использует дополнительные правила из этой директории(ий).
`--fix`	Автоматически исправляет проблемы линтинга.
`--fix-type <fixType>`	Указывает типы исправлений для применения (например, problem, suggestion, layout).
`--ignore-path <path>`	Указывает файл для игнорирования.
`--no-ignore <path>`	Отключает опцию `--ignore-path`.
`--quiet`	Отображает только ошибки.
`--max-warnings [maxWarnings]`	Указывает количество предупреждений перед срабатыванием ненулевого кода выхода. (по умолчанию: -1)
`-o, --output-file, <outputFile>`	Указывает файл для записи отчёта.
`-f, --format, <format>`	Использует определённый формат вывода.
`--no-inline-config`	Запрещает комментариям изменять конфигурацию или правила.
`--report-unused-disable-directives-severity <level>`	Указывает уровень серьёзности для неиспользуемых директив eslint-disable. (варианты: "error", "off", "warn")
`--no-cache`	Отключает кэширование.
`--cache-location, <cacheLocation>`	Указывает расположение кэша.
`--cache-strategy, [cacheStrategy]`	Указывает стратегию для обнаружения изменённых файлов в кэше. (по умолчанию: "metadata")
`--error-on-unmatched-pattern`	Сообщает об ошибках при несоответствии шаблонов файлов.
`-h, --help`	Отображает это сообщение.

Опции `next telemetry`

Next.js собирает полностью анонимные данные телеметрии об общем использовании. Участие в этой анонимной программе является добровольным, и вы можете отказаться, если не хотите делиться информацией.

Для команды next telemetry доступны следующие опции:

Опция	Описание
`-h, --help`	Показать все доступные опции.
`--enable`	Включает сбор телеметрии Next.js.
`--disable`	Отключает сбор телеметрии Next.js.

Подробнее о Телеметрии.

Примеры

Изменение порта по умолчанию

По умолчанию Next.js использует http://localhost:3000 в режиме разработки и с командой next start. Порт по умолчанию можно изменить с помощью опции -p, например:

Terminal

next dev -p 4000

Или используя переменную окружения PORT:

Terminal

PORT=4000 next dev

Полезно знать: PORT нельзя задать в файле .env, так как HTTP-сервер запускается до инициализации какого-либо кода.

Использование HTTPS в режиме разработки

Для некоторых сценариев, таких как вебхуки или аутентификация, может потребоваться использование HTTPS для создания безопасного окружения на localhost. Next.js может генерировать самоподписанный сертификат с помощью команды next dev и флага --experimental-https:

Terminal

next dev --experimental-https

Также можно указать собственные ключ и сертификат с помощью --experimental-https-key и --experimental-https-cert. Дополнительно можно указать собственный CA-сертификат с помощью --experimental-https-ca.

Terminal

next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem

next dev --experimental-https предназначен только для разработки и создаёт локально доверенный сертификат с помощью mkcert. В продакшене используйте сертификаты, выданные доверенными центрами сертификации.

Полезно знать: При деплое на Vercel HTTPS настраивается автоматически для вашего Next.js-приложения.

Настройка таймаута для нижестоящих прокси

При развертывании Next.js за нижестоящим прокси (например, за балансировщиком нагрузки вроде AWS ELB/ALB) важно настроить базовый HTTP-сервер Next.js с таймаутами keep-alive, которые больше, чем таймауты нижестоящего прокси. В противном случае, как только будет достигнут таймаут keep-alive для TCP-соединения, Node.js немедленно завершит это соединение без уведомления нижестоящего прокси. Это приводит к ошибке прокси при попытке повторно использовать соединение, которое Node.js уже завершил.

Для настройки значений таймаута для продакшен-сервера Next.js передайте --keepAliveTimeout (в миллисекундах) в next start, например:

Terminal

next start --keepAliveTimeout 70000

Передача аргументов Node.js

Вы можете передавать любые аргументы Node.js в команды next. Например:

Terminal

NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next

Справочник

Команды

Опции `next dev`

Опции `next build`

Опции `next start`

Опции `next info`

Опции `next lint`

Опции `next telemetry`

Примеры

Изменение порта по умолчанию

Использование HTTPS в режиме разработки

Настройка таймаута для нижестоящих прокси

Передача аргументов Node.js

On this page