Statische Routen und 404-Fehler

Eine Website mit erzeugten Inhalten sollte für jede Route deren HTML ausliefern und für eine fehlende Seite HTTP 404 zurückgeben. Neue lizardpack-Builds für Astro static, Docusaurus, VitePress, Hugo und SvelteKit adapter-static verwenden diese Richtlinie. React- und Vue-SPAs behalten den index.html-Fallback, den Browser-Router benötigen.

Die benutzerdefinierte Konfiguration unten ist optional. Verwenden Sie sie für eine Routing-Richtlinie, die das erkannte Framework nicht bereitstellt. Bestehende Images behalten ihre alten Regeln, bis Sie sie neu bauen.

Wählen Sie die Routing-Richtlinie

App-Typ	Routenverhalten
React- oder Vue-SPA	Eine gültige Client-Route lädt `index.html`, danach rendert der Client-Router sie.
Erzeugte Dokumentation oder Inhalte	Eine Route wird zu ihrem erzeugten HTML aufgelöst; ein unbekannter Pfad gibt HTTP 404 zurück.
Serverseitig gerenderte App	Der Anwendungsserver löst Routen auf und gibt den Status zurück.

Eine SPA-Catch-all-Ansicht kann eine Meldung für fehlende Seiten anzeigen, aber Browser-Code kann den HTTP-Status der bereits gesendeten HTML-Antwort nicht ändern. Wenn Sie für eine SPA routenabhängigen HTTP-Status benötigen, verwenden Sie einen Server oder ein Prerendering-Routing-Setup, das weiß, welche Pfade existieren.

nginx für erzeugte Seiten konfigurieren

Erstellen Sie nginx.conf im Anwendungsstamm:

server {
  listen 80;
  server_name _;
  root /usr/share/nginx/html;
  index index.html;
 
  location / {
    try_files $uri $uri.html $uri/ =404;
  }
 
  error_page 404 /404.html;
  location = /404.html {
    internal;
  }
}

Dies unterstützt sowohl guide.html- als auch guide/index.html-Ausgabelayouts. Fügen Sie ein erzeugtes 404.html ein, wenn Sie eine benutzerdefinierte Fehlerseite möchten. Lassen Sie andernfalls die error_page- und Exact-Location-Blöcke weg, um den Standard-Fehlertext von nginx zu verwenden. Behalten Sie in den Links und der Sitemap der Website einen kanonischen URL-Stil bei; diese Suchregel fügt keine kanonischen Weiterleitungen hinzu.

Website mit der Konfiguration bauen

Verwenden Sie dieses vollständige Dockerfile für ein npm-Projekt mit einer eingecheckten Lockfile. Passen Sie die Standardwerte für BUILD_SCRIPT und OUTPUT_DIR an die folgende Tabelle an:

FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
ARG BUILD_SCRIPT=build
RUN npm run "$BUILD_SCRIPT"
 
FROM nginx:alpine
ARG OUTPUT_DIR=dist
COPY --from=build /app/${OUTPUT_DIR}/ /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

Website	`BUILD_SCRIPT`	`OUTPUT_DIR`
Astro static	`build`	`dist`
Docusaurus	`build`	`build`
VitePress mit einem `docs/`-Stamm	`docs:build`	`docs/.vitepress/dist`
VitePress im Projektstamm	`docs:build` oder Ihr tatsächliches Skript	`.vitepress/dist`
SvelteKit mit adapter-static	`build`	`build`
Next.js export	`build`	`out`
Nuxt generate	`build` mit `nuxt generate`	`.output/public`

Verwenden Sie die Richtlinie für erzeugte Seiten nur, wenn die App diese Routendateien hat. Ein SvelteKit-SPA-Fallback benötigt zum Beispiel seine eigene Routing-Richtlinie. Next.js statischer Export enthält eine vollständige Anleitung mit einem Trailing-Slash-Layout.

Schließen Sie Abhängigkeiten, Build-Ausgabe, .git und .env* in .dockerignore aus. Wenn der Build öffentliche Variablen benötigt, deklarieren Sie ihre ARG-Werte vor dem Build-Befehl. Kopieren Sie keine privaten Secrets in das Image oder die Browser-Ausgabe.

Nach der CLI-Einrichtung erstellen Sie einen Service mit lizard add --service web und stellen dann diesen Quellcode mit lizard up --service web --port 80 bereit. Überspringen Sie den Schritt zum Hinzufügen, wenn der Service bereits existiert. Prüfen Sie bei einem bestehenden Service die Reihenfolge der Build-Entscheidung: Befehlsüberschreibungen können Vorrang vor dem Dockerfile haben. Eine Konfigurationsdatei allein ersetzt die erzeugte nginx-Konfiguration nicht; das Dockerfile muss sie in das Image kopieren.

HTTP-Antworten prüfen

Setzen Sie SITE_URL auf die tatsächliche lokale Test-URL oder die bereitgestellte Origin und ersetzen Sie dann /guide/ durch eine Seite, die existiert:

SITE_URL=https://YOUR_PUBLIC_HOST
curl -sS -o /dev/null -w '%{http_code}\n' "$SITE_URL/"
curl -sS -o /dev/null -w '%{http_code}\n' "$SITE_URL/guide/"
curl -sS -o /dev/null -w '%{http_code}\n' "$SITE_URL/this-page-does-not-exist"

Erwarten Sie 200 für echte Seiten und 404 für den fehlenden Pfad. Wenn eine gültige Route zu ihrer kanonischen Form weiterleitet, prüfen Sie die Weiterleitung und verifizieren Sie dann das Ziel. Testen Sie auch ein tatsächliches Asset und einen erfundenen .js-Pfad: Ein fehlendes Skript darf nicht die Startseite als HTML mit Status 200 zurückgeben.

Öffnen Sie die innere Route abschließend direkt in einem Browser und laden Sie sie neu. Korrekte Client-Navigation allein kann einen Server-Routing-Fehler verbergen. Prüfen Sie vor der Veröffentlichung einer indexierten Website zusammen mit dem HTTP-Status auch die Einstellungen des Frameworks für kanonische URLs und die Sitemap.

Unter getestete Versionen und Cloud-Ergebnisse finden Sie die Deployment-Prüfungen vom 9. September 2026 und ihre Grenzen.

Hugo Getestete Versionen & Ergebnisse