Хостинг Next.js на своём сервере с развёртыванием по git push

Кратко, чтобы разместить Next.js на своём сервере, установите панель развёртывания вроде Coolify и подключите репозиторий GitHub. После этого каждый git push собирает приложение и выкладывает новую версию по HTTPS. Согласно документации Next.js, при развёртывании с сервером Node.js или контейнером Docker работают все возможности, так что вы не привязаны к какой-то особой платформе.

Какие возможности работают на своём сервере?

Таблица в официальной документации короткая: сервер Node.js и Docker поддерживают все возможности, а статический экспорт ограничен. На одном сервере это на практике означает следующее:

• Серверные компоненты, маршруты API и потоковые ответы работают с next start.
• next/image не требует дополнительной настройки, а изображения обрабатываются на сервере.
• Кэширование и инкрементальная статическая регенерация (ISR) работают сами на одном сервере с постоянным диском. Если вы запускаете несколько копий, кэш между ними нужно делать общим.
• Официальная рекомендация — не выставлять Next.js напрямую, а поставить перед ним обратный прокси. Для этого в Coolify есть Traefik, он же получает сертификат.

Насколько мощным должен быть сервер?

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

Небольшим проектом было пример-приложение Next.js из Coolify. Крупнее был ИИ-чат на Next.js 16 примерно с 85 пакетами, и на 2 ГБ ему не хватило памяти во время проверки TypeScript. На сервере было 2 ГБ подкачки, а цифры показывают пиковое значение. После первой сборки занято 13–18 ГБ диска. Это наши собственные замеры, и ваш проект будет отличаться. Если сборка падает из-за нехватки памяти, сначала увеличьте сервер, а позже при возможности вернитесь на меньший размер.

Шаг за шагом

1. Подключите репозиторий

Войдите в Coolify, откройте свой проект на странице Projects и нажмите New resource. Для публичного репозитория выберите Public Git Repository, введите адрес и нажмите Check repository.

2. Добавьте ключ, если репозиторий приватный

В левом меню откройте Private Keys в разделе Keys & Tokens и создайте ключ через Generate ED25519. Добавьте открытый ключ в Deploy keys на странице Settings репозитория на GitHub. Затем через New resource выберите Private Git Repository (with Deploy Key) и введите [email protected]:user/project.git. Оставьте для Build pack значение Railpack, который распознаёт Next.js, порт остаётся 3000. Coolify помечает Railpack как бета-версию, поэтому при проблемах выберите собственный Dockerfile.

3. Введите переменные окружения

На странице Environment Variables переключитесь на Developer view и вставьте содержимое своего файла .env. Здесь важна одна деталь: переменные, имена которых начинаются с NEXT_PUBLIC_, записываются в код во время сборки. Когда вы меняете такую переменную, нажмите Redeploy: панель видит, что изменилась настройка сборки, и собирает заново. Никогда не давайте этот префикс ключу, который браузер видеть не должен.

4. Подключите домен

У своего поставщика домена создайте A-запись, указывающую на IP-адрес сервера. В Coolify откройте страницу Domains, нажмите Add domain, выберите протокол https, введите свой домен, сохраните и разверните заново. Сертификат запрашивается и продлевается автоматически. Порты 80 и 443 должны быть открыты.

5. Разверните

Нажмите Deploy. На странице Deployments журнал сборки виден в реальном времени. Когда сборка завершится, старый контейнер продолжает обслуживать запросы, пока новый не будет готов.

Как git push превращается в развёртывание?

При каждом пуше GitHub отправляет панели подписанный запрос. Панель проверяет подпись и пересобирает приложение для этой ветки, а запрос с неверной подписью отклоняется. Настраивается это так:

1. На странице Webhooks приложения скопируйте Webhook URL из раздела GitHub, введите в Webhook secret случайное значение не короче 16 символов и сохраните.
2. На GitHub откройте Settings репозитория, перейдите в Webhooks и нажмите Add webhook.
3. Укажите адрес в Payload URL и то же значение в Secret. Для Content type выберите application/json и оставьте единственным событием push.

Чтобы попробовать:

git commit --allow-empty -m "deploy test"

git push

Новая сборка появится на странице Deployments. На небольшом примере проекта новый коммит вышел в работу за 41 секунду благодаря кэшу сборки. GitHub должен иметь доступ к адресу панели, а поскольку панель устанавливается с публичным адресом HTTPS, ничего дополнительно не нужно.

Типичные ошибки

В варианте Next.js в Seturack Coolify приходит уже установленным: локальный сервер проверен, приветственный мастер пройден, а панель открывается по HTTPS. Адрес и пароль появляются в вашей панели, и начинать нужно с подключения GitHub. Доступ root у вас есть, и при желании всем можно управлять из панели. Ежедневные бэкапы входят в цену, а трафик безлимитный. Размер вы задаёте ползунками на странице Next.js VPS.

Готовое решение на Seturack: Next.js, Coolify.