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

Next.js Docker-image met uitvoer: 'standalone': build in meerdere fasen en niet-root

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

Waarom zelfstandig

Een gewone Next.js-afbeelding kopieert de volledige node_modules samen met devDependencies, bronnen en build-cache. Met output: 'standalone' traceert Next.js, wanneer gebouwd, welke bestanden de server daadwerkelijk nodig heeft en plaatst deze in .next/standalone samen met het minimum server.js. Alleen dit, statisch en public komen in de uiteindelijke afbeelding terecht.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};
export default nextConfig;

Voeg in een monorepository outputFileTracingRoot toe met het pad naar de root van de repository, anders zal de tracering geen pakketten uit aangrenzende mappen vinden.

Dockerbestand

# 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"]

Analyse van oplossingen:

  • Drie fasen. Compilers, devDependencies en bronnen blijven in tussenfasen en komen niet in het uiteindelijke beeld terecht.
  • `--mount=type=cache` behoudt npm-cache tussen builds op dezelfde machine. Dit is een BuildKit-functie, vandaar de regel # syntax aan het begin.
  • `HOSTNAME=0.0.0.0`. server.js luistert naar het adres van deze variabele. Zonder dit kan de server zich binden aan de containernaam en zal de doorgestuurde poort reageren met een verbindingsfout.
  • Statistieken worden afzonderlijk gekopieerd. .next/standalone bevat niet .next/static en public - dit is een veelvoorkomende oorzaak van 404 op CSS en JS na de eerste build.
  • `USER node`. Officiële knooppuntimages hebben al een gebruiker zonder rechten node (uid 1000). Het is niet nodig om uw eigen bestanden te maken, maar de bestanden moeten worden gekopieerd van --chown, anders kan het proces niet naar .next/cache schrijven voor ISR en beeldoptimalisatie.

Omgevingsvariabelen: build en runtime

NEXT_PUBLIC_*-variabelen worden vervangen in client-JavaScript tijdens next build. Het is te laat om ze over te zetten met docker run - de bundel bevat al een waarde uit de assembly of is leeg. Daarom doorlopen ze ARG in de bouwerfase.

Servergeheimen (DATABASE_URL, API-sleutels) mogen daarentegen niet in de afbeelding worden opgenomen. Geef ze niet door als ARG en kopieer .env niet - stel ze in bij het opstarten:

docker run -d --env-file /etc/myapp/prod.env -p 127.0.0.1:3000:3000 myapp:1.4.0

En zorg ervoor dat je .dockerignore gebruikt, anders zal COPY . . onnodige dingen naar de assemblagecontext slepen, inclusief geheimen:

node_modules
.next
.git
.env*
*.log
coverage

PID 1 en het stoppen van de container

Een knooppuntproces dat als PID 1 wordt uitgevoerd, ontvangt niet het standaardkernelgedrag voor signalen. Als de applicatie geen SIGTERM-handler heeft, wacht docker stop op een time-out (standaard 10 seconden) en beëindigt het proces via SIGKILL, waardoor actieve verzoeken worden beëindigd. Een eenvoudige oplossing is het init-proces:

# 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

De slanke afbeelding heeft geen curl, dus de healthcheck is in Node zelf geschreven: de globale fetch is beschikbaar in Node 18 en hoger.

Afbeeldingen en scherp

In Next.js 15 wordt sharp automatisch verbonden met next start en in stand-alone modus; het is niet nodig om het handmatig te installeren. Als je nog steeds een waarschuwing ziet over de afwezigheid van Sharp, controleer dan of de build en runtime zich op hetzelfde platform bevinden: binaire bestanden die voor glibc zijn gecompileerd, werken niet op Alpine (musl), en omgekeerd. Daarom komen in het voorbeeld alle fasen uit één basisafbeelding.

Hoe het resultaat te controleren

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

Om te analyseren wat ruimte in beslag neemt in lagen, is de tool dive handig. Als de uiteindelijke afbeelding onverwacht groot is, bevat deze meestal de volledige node_modules: controleer of er geen COPY . . in de runner zit.

Veelgemaakte fouten

  • 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