Docker-образ Next.js с output: 'standalone': multi-stage сборка и non-root
Зачем standalone
Обычный образ Next.js копирует весь node_modules вместе с devDependencies, исходники и кэш сборки. С output: 'standalone' Next.js при сборке трассирует, какие файлы реально нужны серверу, и складывает их в .next/standalone вместе с минимальным server.js. В финальный образ попадает только это, статика и public.
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone",
};
export default nextConfig;В монорепозитории добавьте outputFileTracingRoot с путём к корню репозитория, иначе трассировка не найдёт пакеты из соседних папок.
Dockerfile
# syntax=docker/dockerfile:1
FROM node:22-bookworm-slim AS base
ENV NEXT_TELEMETRY_DISABLED=1
WORKDIR /app
# 1. Только зависимости — слой кэшируется, пока не меняется lock-файл
FROM base AS deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
# 2. Сборка
FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ARG NEXT_PUBLIC_SITE_URL
ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
RUN npm run build
# 3. Рантайм
FROM base AS runner
ENV NODE_ENV=production \
PORT=3000 \
HOSTNAME=0.0.0.0
COPY --from=builder --chown=node:node /app/public ./public
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
USER node
EXPOSE 3000
CMD ["node", "server.js"]Разбор решений:
- Три стадии. Компиляторы, devDependencies и исходники остаются в промежуточных стадиях и в финальный образ не попадают.
- `--mount=type=cache` сохраняет кэш npm между сборками на одной машине. Это BuildKit-функция, отсюда строка
# syntaxв начале. - `HOSTNAME=0.0.0.0`.
server.jsслушает адрес из этой переменной. Без неё сервер может привязаться к имени контейнера, и проброшенный порт будет отвечать отказом соединения. - Статика копируется отдельно.
.next/standaloneне содержит.next/staticиpublic— это частая причина 404 на CSS и JS после первой сборки. - `USER node`. В официальных образах Node уже есть непривилегированный пользователь
node(uid 1000). Создавать своего не обязательно, но файлы нужно копировать с--chown, иначе процесс не сможет писать в.next/cacheдля ISR и оптимизации изображений.
Переменные окружения: сборка и рантайм
Переменные NEXT_PUBLIC_* подставляются в клиентский JavaScript во время next build. Передать их при docker run поздно — в бандле уже лежит значение со сборки или пустота. Поэтому они идут через ARG в стадии builder.
Серверные секреты (DATABASE_URL, ключи API) наоборот не должны попадать в образ. Не передавайте их как ARG и не копируйте .env — задавайте при запуске:
docker run -d --env-file /etc/myapp/prod.env -p 127.0.0.1:3000:3000 myapp:1.4.0
И обязательно .dockerignore, иначе COPY . . утащит в контекст сборки лишнее, включая секреты:
node_modules .next .git .env* *.log coverage
PID 1 и остановка контейнера
Процесс Node, запущенный как PID 1, не получает стандартного поведения ядра для сигналов. Если в приложении нет обработчика SIGTERM, docker stop ждёт таймаут (по умолчанию 10 секунд) и убивает процесс через SIGKILL, обрывая активные запросы. Простое решение — init-процесс:
# compose.yml
services:
web:
image: myapp:1.4.0
init: true
env_file: /etc/myapp/prod.env
ports:
- "127.0.0.1:3000:3000"
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
interval: 30s
timeout: 5s
retries: 3В slim-образе нет curl, поэтому healthcheck написан на самом Node: глобальный fetch доступен в Node 18 и новее.
Изображения и sharp
В Next.js 15 sharp подключается автоматически при next start и в standalone-режиме, ставить его вручную не нужно. Если всё же видите предупреждение об отсутствии sharp, проверьте, что сборка и рантайм на одной платформе: бинарники, собранные под glibc, не работают на Alpine (musl), и наоборот. Поэтому в примере все стадии от одного базового образа.
Как проверить результат
docker build -t myapp:test --build-arg NEXT_PUBLIC_SITE_URL=https://example.com . docker image ls myapp:test # размер образа docker run --rm myapp:test id # uid=1000(node), не root docker run --rm myapp:test ls -la .next # владелец node
Для разбора, что занимает место по слоям, удобен инструмент dive. Если финальный образ неожиданно большой, обычно в него попал node_modules целиком: проверьте, что в runner нет COPY . ..
Типичные ошибки
Error: EACCESпри записи в.next/cache— файлы скопированы без--chown.- Сайт работает, но без стилей — забыли скопировать
.next/static. NEXT_PUBLIC_*пустые в браузере — переданы в рантайме, а не при сборке.- Сборка на Mac с Apple Silicon, запуск на amd64-сервере — нужна
docker buildx build --platform linux/amd64, иначе нативные модули не той архитектуры.
Когда standalone не нужен
Если деплой идёт на Vercel или другую платформу со своей сборкой, эта настройка ничего не даёт. Для статического экспорта (output: 'export') сервер не нужен вовсе — хватит nginx со статикой.