Next.js Docker-image met uitvoer: 'standalone': build in meerdere fasen en niet-root
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
# syntaxaan het begin. - `HOSTNAME=0.0.0.0`.
server.jsluistert 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/standalonebevat niet.next/staticenpublic- 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/cacheschrijven 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: 3De 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 со статикой.