<span id="static-routes-and-404s" />

# 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.

<span id="choose-the-routing-policy" />

## 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.

<span id="configure-nginx-for-generated-pages" />

## nginx für erzeugte Seiten konfigurieren

Erstellen Sie `nginx.conf` im Anwendungsstamm:

```nginx
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.

<span id="build-the-site-with-the-config" />

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

```dockerfile
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](https://lizard.build/de/docs/framework-guides/nextjs/static-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](https://lizard.build/de/docs/framework-guides#prepare-the-project) 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](https://lizard.build/de/docs/concepts/build-pipeline#build-decision-order): 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.

<span id="verify-http-responses" />

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

```bash
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](https://lizard.build/de/docs/framework-guides/validation) finden Sie die Deployment-Prüfungen vom 9. September 2026 und ihre Grenzen.