Как упаковать 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 есть два принципиально разных способа работы с переменными окружения.
- 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 после сборки нельзя.
- Серверные переменные — 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 buildNext.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 / Standalone | next build | .next/standalone | Node.js |
| Static Export | next build | out/ | 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 SSR | output: "standalone" |
| Сборка | npm run build |
| Точка входа | node server.js |
| Host | HOSTNAME=0.0.0.0 |
| Port | PORT=3000 |
| Клиентские переменные | NEXT_PUBLIC_* |
| Серверные переменные | process.env.* |
| Статический сайт | output: "export" |
| Каталог статики | out/ |
| Production-сервер статики | Nginx |
| Разработка | next dev --hostname 0.0.0.0 |