Next.js-Docker-Image mit Ausgabe: „standalone“: mehrstufiger Build und kein Root
Warum eigenständig
Ein reguläres Next.js-Image kopiert den gesamten node_modules zusammen mit DevDependencies, Quellen und Build-Cache. Mit output: 'standalone' verfolgt Next.js beim Erstellen, welche Dateien der Server tatsächlich benötigt, und fügt sie zusammen mit dem Mindestwert server.js in .next/standalone ein. Nur dies, static und public landen im endgültigen Bild.
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone",
};
export default nextConfig;Fügen Sie in einem Monorepository outputFileTracingRoot mit dem Pfad zum Repository-Stamm hinzu, andernfalls findet der Trace keine Pakete aus benachbarten Ordnern.
Docker-Datei
# 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 der Lösungen:
- Drei Stufen. Compiler, Entwicklungsabhängigkeiten und Quellen verbleiben in Zwischenstufen und landen nicht im endgültigen Image.
- `--mount=type=cache` behält den NPM-Cache zwischen Builds auf demselben Computer bei. Dies ist eine BuildKit-Funktion, daher die Zeile
# syntaxam Anfang. - `HOSTNAME=0.0.0.0`.
server.jshört auf die Adresse dieser Variablen. Ohne sie kann sich der Server an den Containernamen binden und der weitergeleitete Port antwortet mit einem Verbindungsfehler. - Statikdaten werden separat kopiert.
.next/standaloneenthält nicht.next/staticundpublic– dies ist eine häufige Ursache für 404 in CSS und JS nach dem ersten Build. - `USER node`. Offizielle Node-Images haben bereits einen unprivilegierten Benutzer
node(UID 1000). Es ist nicht notwendig, eigene Dateien zu erstellen, aber die Dateien müssen von--chownkopiert werden, andernfalls kann der Prozess für ISR und Bildoptimierung nicht nach.next/cacheschreiben.
Umgebungsvariablen: Build und Laufzeit
NEXT_PUBLIC_*-Variablen werden während next build in Client-JavaScript ersetzt. Es ist zu spät, sie mit docker run zu übertragen – das Bundle enthält bereits einen Wert aus der Assembly oder ist leer. Daher durchlaufen sie in der Builder-Phase ARG.
Servergeheimnisse (DATABASE_URL, API-Schlüssel) sollten hingegen nicht im Bild enthalten sein. Übergeben Sie sie nicht als ARG und kopieren Sie nicht .env – legen Sie sie beim Start fest:
docker run -d --env-file /etc/myapp/prod.env -p 127.0.0.1:3000:3000 myapp:1.4.0
Und achten Sie darauf, .dockerignore zu verwenden, sonst zieht COPY . . unnötige Dinge in den Assembly-Kontext, einschließlich Geheimnisse:
node_modules .next .git .env* *.log coverage
PID 1 und Stoppen des Containers
Ein Knotenprozess, der als PID 1 ausgeführt wird, empfängt nicht das Standardkernelverhalten für Signale. Wenn die Anwendung keinen SIGTERM-Handler hat, wartet docker stop auf eine Zeitüberschreitung (standardmäßig 10 Sekunden) und bricht den Prozess über SIGKILL ab, wodurch aktive Anforderungen beendet werden. Eine einfache Lösung ist der Init-Prozess:
# 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: 3Das Slim-Image verfügt nicht über curl, daher wird der Gesundheitscheck in Node selbst geschrieben: Der globale fetch ist in Node 18 und höher verfügbar.
Bilder und scharf
In Next.js 15 wird sharp automatisch mit next start und im Standalone-Modus verbunden; Es ist nicht erforderlich, es manuell zu installieren. Wenn immer noch eine Warnung über das Fehlen von Sharp angezeigt wird, überprüfen Sie, ob sich Build und Laufzeit auf derselben Plattform befinden: Für glibc kompilierte Binärdateien funktionieren nicht auf Alpine (musl) und umgekehrt. Daher stammen im Beispiel alle Stufen aus einem Grundbild.
So überprüfen Sie das Ergebnis
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
Um zu analysieren, was in Ebenen Platz einnimmt, ist das Tool dive praktisch. Wenn das endgültige Bild unerwartet groß ist, enthält es normalerweise den gesamten node_modules: Überprüfen Sie, ob im Läufer kein COPY . . vorhanden ist.
Häufige Fehler
Error: EACCESbeim Schreiben nach.next/cache– Dateien wurden ohne--chownkopiert.- Die Seite funktioniert, aber ohne Stile – sie haben vergessen,
.next/staticzu kopieren. NEXT_PUBLIC_*leer im Browser – wird zur Laufzeit übertragen, nicht während der Assemblierung.- Auf einem Mac mit Apple Silicon erstellen, auf einem amd64-Server ausführen – Sie benötigen
docker buildx build --platform linux/amd64, sonst haben die nativen Module die falsche Architektur.
Wenn Standalone nicht benötigt wird
Wenn die Bereitstellung auf Vercel oder eine andere Plattform mit eigener Assembly erfolgt, bringt diese Einstellung nichts. Für den statischen Export (output: 'export') ist überhaupt kein Server erforderlich – Nginx mit Statik reicht aus.