re:re:actable
Урок 039 минут чтения

Как упаковать Next.js-приложение в Docker

На этой странице

Next.js с SSR, Server Components, Route Handlers (app/api) и Server Actions — это Node.js-приложение, а не просто набор статических файлов. Команда next build создаёт production-сборку в .next, а next start запускает сервер Next.js.

Для Docker рекомендуется использовать Standalone Output (output: "standalone"). Next.js автоматически формирует минимальный набор файлов для production: сервер, необходимые зависимости и статические ресурсы. В финальный Docker-образ не нужно копировать весь node_modules.

Переменные окружения, используемые на сервере через process.env, можно передавать при запуске контейнера. Но значения NEXT_PUBLIC_* подставляются в клиентский JavaScript во время сборки и после неё не меняются.

Что лежит в .next/standalone

Включаем Standalone Output в next.config.ts:

import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  output: "standalone",
};
 
export default nextConfig;

После npm run build структура примерно следующая:

.next/
  standalone/
    server.js             ← точка входа Node.js
    package.json
    node_modules/         ← минимальный набор зависимостей
    .next/
      server/             ← серверная сборка Next.js
  static/                 ← клиентские JS/CSS и другие ассеты
  server/
  cache/

Важный нюанс: .next/static и папку public нужно отдельно скопировать в standalone-образ. Они не включаются в standalone автоматически.

Standalone Output использует трассировку зависимостей, чтобы включить только необходимые файлы. Это позволяет существенно уменьшить production-образ.

Production Dockerfile

Рекомендуемая структура — четыре stage: base, deps, build, runner.

# syntax=docker/dockerfile:1
 
FROM node:24-alpine AS base
WORKDIR /app
 
FROM base AS deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
 
FROM base AS build
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
ENV NEXT_TELEMETRY_DISABLED=1
 
RUN npm run build
 
FROM base AS runner
 
ENV NODE_ENV=production \
    NEXT_TELEMETRY_DISABLED=1 \
    HOSTNAME=0.0.0.0 \
    PORT=3000
 
RUN addgroup --system --gid 1001 nodejs \
    && adduser --system --uid 1001 nextjs
 
COPY --from=build --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=build --chown=nextjs:nodejs /app/.next/static ./.next/static
 
# Если в проекте есть public
COPY --from=build --chown=nextjs:nodejs /app/public ./public
 
USER nextjs
 
EXPOSE 3000
 
CMD ["node", "server.js"]

Если каталог public отсутствует, его нужно создать в проекте или убрать соответствующую инструкцию COPY.

server.js автоматически генерируется Next.js при включённом output: "standalone".

В отличие от обычного запуска через next start, здесь запускается непосредственно standalone-сервер.

Почему такая структура:

  • deps — устанавливает зависимости через npm ci.

  • build — собирает Next.js-приложение.

  • runner — содержит только production-файлы.

  • USER nextjs — запускает приложение без root-прав.

  • HOSTNAME=0.0.0.0 — делает сервер доступным за пределами контейнера.

.dockerignore

Добавляем .dockerignore, чтобы не отправлять лишние файлы в Docker build context:

node_modules
.next
.git
.gitignore
.env
.env.*
!.env.example
npm-debug.log*
Dockerfile*
compose.yaml

Не исключайте из контекста файлы, которые действительно нужны для сборки, например next.config.ts, tsconfig.json и исходный код.

Переменные окружения: build-time и runtime

В Next.js есть два принципиально разных способа работы с переменными окружения.

  1. NEXT_PUBLIC_ — build-time*

Переменные с префиксом NEXT_PUBLIC_ автоматически встраиваются в клиентский JavaScript во время next build.

Например:

NEXT_PUBLIC_API_URL=https://api.example.com

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

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

После сборки значение становится частью клиентского бандла.

Поэтому изменить его через docker run -e после сборки нельзя.

  1. Серверные переменные — runtime

Переменные без NEXT_PUBLIC_ можно читать на сервере через process.env.

Например:

const databaseUrl = process.env.DATABASE_URL;
const authSecret = process.env.AUTH_SECRET;

Передаём их при запуске контейнера:

docker build -t next-app .
 
docker run \
  -e DATABASE_URL=postgres://app:secret@db:5432/app \
  -e AUTH_SECRET=super-secret \
  -e NEXT_PUBLIC_API_URL=https://api.example.com \
  -p 3000:3000 \
  next-app

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

В App Router для принудительного динамического рендеринга можно использовать:

import { connection } from "next/server";
 
export default async function Page() {
  await connection();
 
  const apiUrl = process.env.INTERNAL_API_URL;
 
  return <div>{apiUrl}</div>;
}

Это позволяет читать серверные переменные во время обработки запроса.

Таким образом, можно использовать один Docker-образ для разных окружений:

  • Development.

  • Staging.

  • Production.

Меняются только переменные окружения контейнера.

Важно: никогда не помещайте секреты в NEXT_PUBLIC_*. Всё, что попадает в клиентский JavaScript, доступно пользователю.

Кэш и несколько реплик

Next.js использует несколько механизмов кэширования:

  • Data Cache — результаты запросов к данным.

  • Full Route Cache — статически сгенерированные страницы.

  • Router Cache — клиентский кэш маршрутов.

  • Image Cache — оптимизированные изображения.

При самостоятельном размещении Next.js использует файловую систему и память процесса для части кэшей.

При запуске нескольких Docker-реплик возникают особенности:

  • У каждой реплики может быть собственный локальный кэш.

  • Инвалидация кэша на одной реплике не обязательно синхронизирует остальные.

  • Локальные файлы кэша могут исчезнуть при пересоздании контейнера.

Для горизонтального масштабирования рекомендуется настроить общий Cache Handler.

Например, можно использовать Redis через собственный Cache Handler:

// next.config.ts
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  output: "standalone",
 
  cacheHandler: require.resolve("./cache-handler.js"),
 
  cacheMaxMemorySize: 0,
};
 
export default nextConfig;

Сам cache-handler.js необходимо реализовать или подключить как отдельный модуль, обеспечив чтение, запись и инвалидацию кэша через Redis.

Также для нескольких реплик важно учитывать согласованность секретов и конфигурации, используемых Server Actions.

Изображения

Next.js имеет встроенный компонент next/image, который оптимизирует изображения на сервере.

Пример:

import Image from "next/image";
 
export default function Page() {
  return (
    <Image
      src="/images/photo.jpg"
      alt="Photo"
      width={800}
      height={600}
    />
  );
}

В production оптимизация изображений требует работающего Next.js-сервера.

Для production рекомендуется установить sharp:

npm install sharp

Если приложение использует Alpine Linux, стоит проверить совместимость нативных зависимостей sharp с используемым образом Node.js.

Если изображения оптимизирует внешний CDN, можно использовать кастомный loader или отключить встроенную оптимизацию через unoptimized.

Важно: при использовании standalone нужно отдельно копировать .next/static, иначе клиентские JS/CSS-файлы не будут доступны.

Статический Next.js

Если SSR не нужен, Next.js можно собрать как статический сайт.

Для этого используется output: "export" вместо output: "standalone".

Настройка next.config.ts:

import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  output: "export",
};
 
export default nextConfig;

Запускаем сборку:

npm run build

Next.js создаст каталог out/:

out/
  index.html
  about.html
  404.html
  _next/
    static/
      chunks/
      css/
  images/
  ...

Упаковываем его в Nginx:

FROM node:24-alpine AS build
 
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN npm ci
 
COPY . .
 
RUN npm run build
 
FROM nginx:1.29-alpine
 
COPY --from=build /app/out /usr/share/nginx/html
 
EXPOSE 80

В этом случае Node.js в production не нужен.

Однако у статической сборки есть ограничения:

  • SSR и динамический серверный рендеринг не работают.

  • Route Handlers, требующие выполнения во время запроса, недоступны.

  • Server Actions не работают.

  • Нельзя использовать серверные переменные окружения во время обработки запросов.

  • Динамические маршруты должны быть известны на этапе сборки и пререндерены.

  • Встроенная оптимизация изображений через next/image требует отдельного решения: например, CDN, custom loader или unoptimized.

Статическая сборка подходит для документации, лендингов, блогов и сайтов, содержимое которых можно сформировать заранее.

Главное отличие:

РежимКомандаРезультатProduction
SSR / Standalonenext build.next/standaloneNode.js
Static Exportnext buildout/Nginx

Docker Compose

Пример compose.yaml для Next.js с PostgreSQL:

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://app:secret@db:5432/app
      AUTH_SECRET: super-secret
      NEXT_PUBLIC_API_URL: /api
    depends_on:
      db:
        condition: service_healthy
 
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      retries: 10
 
volumes:
  pgdata:

Запуск:

docker compose up -d --build

Приложение будет доступно по адресу:

http://localhost:3000

Внутри Docker-сети Next.js обращается к PostgreSQL по имени сервиса db, а не localhost.

Для реального production вместо паролей в Compose-файле лучше использовать Docker Secrets или внешний менеджер секретов.

Если при сборке Next.js выполняет статическую генерацию страниц с запросами к БД или API, соответствующие сервисы должны быть доступны уже во время next build.

Это частая причина падений сборки в CI. Если данные должны загружаться при каждом запросе, используйте динамический SSR вместо статической генерации.

Разработка

Для разработки отдельный production Dockerfile не нужен. Можно использовать Docker Compose с Vite-подобным hot reload, который в Next.js обеспечивает Fast Refresh.

services:
  web:
    image: node:24-alpine
    working_dir: /app
    command: sh -c "npm ci && npm run dev -- --hostname 0.0.0.0"
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next

Запуск:

docker compose up

Приложение будет доступно по адресу:

http://localhost:3000

Параметр --hostname 0.0.0.0 нужен, чтобы dev-сервер принимал подключения извне контейнера.

Его также можно задать через переменную окружения:

environment:
  HOSTNAME: 0.0.0.0

Если Fast Refresh не работает на macOS или Windows, можно проверить настройки файлового наблюдателя и использовать polling через WATCHPACK_POLLING=true.

Частые ошибки

  • Запускать next dev или next start вместо standalone-сервера в production Dockerfile.

  • Забыть output: "standalone" и ожидать появления .next/standalone.

  • Не скопировать .next/static в финальный образ.

  • Забыть скопировать public.

  • Запускать контейнер от root без необходимости.

  • Не задать HOSTNAME=0.0.0.0 — сервер будет недоступен извне контейнера.

  • Положить секреты в NEXT_PUBLIC_*.

  • Ожидать, что docker run -e NEXT_PUBLIC_API_URL=... изменит уже собранный клиентский бандл.

  • Использовать серверные переменные в статически сгенерированных страницах, ожидая их обновления при запуске.

  • Раздавать SSR-приложение как статику через Nginx.

  • Использовать несколько реплик без продуманной стратегии синхронизации кэша и конфигурации.

  • Не учитывать доступность БД и API во время next build, если сборка пререндерит страницы с данными.

Что важно помнить

  • next build + output: "standalone" → самодостаточная production-сборка.

  • В финальный образ копируется .next/standalone, .next/static и public.

  • Node.js остаётся в production, поскольку Next.js обслуживает SSR и API.

  • NEXT_PUBLIC_* — build-time и публичные.

  • Обычные серверные process.env — runtime, если код выполняется на сервере при запросе.

  • output: "export" → статический сайт в out/, который можно раздавать через Nginx.

  • Для нескольких реплик нужно продумать общий кэш и согласованность конфигурации.

Мини-шпаргалка

ЗадачаРешение
Production SSRoutput: "standalone"
Сборкаnpm run build
Точка входаnode server.js
HostHOSTNAME=0.0.0.0
PortPORT=3000
Клиентские переменныеNEXT_PUBLIC_*
Серверные переменныеprocess.env.*
Статический сайтoutput: "export"
Каталог статикиout/
Production-сервер статикиNginx
Разработкаnext dev --hostname 0.0.0.0

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам