v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T10:04:00.000Z▲ 0 upvotes

Docker-образ Next.js с output: 'standalone': multi-stage сборка и non-root

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

Зачем 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 со статикой.

Обсуждение (0)

Ещё на vbcd4u.com