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

Next.js-Docker-Image mit Ausgabe: „standalone“: mehrstufiger Build und kein Root

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

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 # syntax am Anfang.
  • `HOSTNAME=0.0.0.0`. server.js hö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/standalone enthält nicht .next/static und public – 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 --chown kopiert werden, andernfalls kann der Prozess für ISR und Bildoptimierung nicht nach .next/cache schreiben.

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: 3

Das 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: EACCES beim Schreiben nach .next/cache – Dateien wurden ohne --chown kopiert.
  • Die Seite funktioniert, aber ohne Stile – sie haben vergessen, .next/static zu 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.

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

Ещё на vbcd4u.com