CLI Next.js

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

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

Terminal

npx 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]`	Директория, в которой будет собираться приложение. Если не указана, используется текущая директория.
`--turbopack`	Запускает режим разработки с использованием Turbopack.
`-p` или `--port <port>`	Указывает номер порта для запуска приложения. По умолчанию: 3000, env: 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-сборку вашего приложения. В выводе отображается информация о каждом маршруте. Например:

Terminal

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

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

Размер: Размер ресурсов, загружаемых при навигации на страницу на стороне клиента. Размер для каждого маршрута включает только его зависимости.
Первая загрузка 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, env: PORT)
`-H` или `--hostname <hostname>`	Указывает имя хоста для запуска приложения (по умолчанию: 0.0.0.0).
`--keepAliveTimeout <keepAliveTimeout>`	Указывает максимальное количество миллисекунд ожидания перед закрытием неактивных соединений.

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

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

Terminal

Операционная система:
  Платформа: 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

С сгенерированным сертификатом сервер разработки Next.js будет доступен по адресу https://localhost:3000. Используется порт по умолчанию 3000, если только не указан другой порт с помощью -p, --port или PORT.

Также можно предоставить собственный сертификат и ключ с помощью --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. В продакшене используйте сертификаты, выданные доверенными центрами сертификации.

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

При развёртывании Next.js за нижестоящим прокси (например, балансировщиком нагрузки, таким как AWS ELB/ALB), важно настроить таймауты keep-alive для базового HTTP-сервера Next.js так, чтобы они были больше, чем таймауты нижестоящего прокси. В противном случае, как только будет достигнут таймаут 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