Next.js Static Export

Next.js statisch
veröffentlichen

Exportieren Sie Ihre Next.js-App zu statischem HTML und Assets, laden Sie das out-Verzeichnis hoch und veröffentlichen Sie die Seite weltweit ohne Node.js-Server.

Setup-Anleitung ansehen
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
// Optional for static deployments
images: { unoptimized: true },
}

module.exports = nextConfig
Static Export aktiviert

Support-Matrix für Static Export

Prüfen Sie vor dem Upload von out, ob die App zum Static-Export-Modell passt.

Funktioniert gut

  • Statische Routen, die zur Build-Zeit erzeugt werden
  • App-Router-Seiten, die statisch gerendert werden können
  • Pages Router mit getStaticProps / getStaticPaths
  • Clientseitiges Datenladen nach Hydration
  • next/link, dynamic imports, CSS Modules und statische Assets

Braucht eine andere Runtime

  • API Routes und Route Handler mit Server-Ausführung
  • Middleware, Rewrites, Redirects und Custom Headers
  • getServerSideProps und Request-Time Rendering
  • Incremental Static Regeneration
  • Standardmäßige next/image-Optimierung ohne statische Strategie

Next.js nutzen, wenn Sie das Framework wollen, nicht den Server

Framework behalten, Server weglassen

Next.js Static Export lässt Sie file-based routing, Layouts, Metadaten, Build-Time Rendering, CSS-Unterstützung und clientseitiges React behalten.

Die Ausgabe ist trotzdem nur ein Satz Dateien. Das passt für Marketingseiten, Docs, Portfolios, Produktseiten, Content-Hubs und andere Seiten, die zur Build-Zeit vorbereitet werden können.

Schnell wie ein statisches Asset

Vorgeneriertes HTML kann aggressiv gecacht und direkt von Edge-Standorten ausgeliefert werden, ohne auf einen Render-Server zu warten.

Weniger Ops-Aufwand

Keine Node-Runtime bedeutet weniger bewegliche Teile, einfachere Artefakte und weniger Drift zwischen Builds.

Klare Runtime-Grenze

Braucht eine Seite Server-Code, sollte sie nicht in einen Static Export gezwungen werden. Kann sie vorab gebaut werden, ist out ein sauberes Artefakt.

Häufige Blocker beim Static Export

Blocker 01

Build scheitert wegen serverseitiger Features

Entfernen Sie Request-Time-APIs aus der exportierten Route, verschieben Sie sie hinter ein separates Backend oder deployen Sie diesen Teil auf einer serverfähigen Plattform.

Blocker 02

Bilder funktionieren in dev, aber nicht nach Export

Der Standard-Optimizer von next/image erwartet einen Server. Nutzen Sie images.unoptimized, einen eigenen Loader oder reguläre statische Bilddateien.

Blocker 03

Dynamische Routen fehlen

Erzeugen Sie die Routenliste zur Build-Zeit mit generateStaticParams im App Router oder getStaticPaths im Pages Router.

Blocker 04

Redirects oder Rewrites greifen nicht

Next.js Redirects und Rewrites sind nicht Teil des Static Export. Nutzen Sie statische Seitenstruktur, clientseitige Navigation oder verfügbare Plattform-Redirects.

Next.js Static Export Checkliste

01

output: 'export' setzen

Weisen Sie Next.js an, zur Build-Zeit statisches HTML auszugeben, statt next start oder eine gehostete Node-Runtime zu erwarten.

output: 'export'
02

Bauen und /out prüfen

Führen Sie den Produktions-Build aus und prüfen Sie, ob out gerenderte Seiten, Assets, 404-Seite und statische Dateien enthält.

npm run build
03

Hochladen und Routen testen

Laden Sie out hoch und prüfen Sie verschachtelte Pfade, statische Assets und unoptimierte Bilder auf der veröffentlichten Seite.

Next.js-Deployment: häufige Fragen

Warum scheitert die Next.js Image-Komponente nach dem Export?

Die Standard-Bildoptimierung erwartet einen Server. Für Static Export setzen Sie images.unoptimized in next.config.js auf true oder nutzen eine statische Bildstrategie.

Funktionieren API Routes oder getServerSideProps hier?

Nein. Static Export entfernt serverseitige Runtime-Features wie API Routes, Middleware und getServerSideProps. Verschieben Sie diese Logik in Backend oder serverlosen Dienst.

Kann ich den App Router nutzen?

Ja, solange die Route statisch gerendert werden kann und nicht von dynamischen Server-APIs wie headers oder cookies abhängt.

Wie gehe ich mit dynamischen Inhalten um?

Laden Sie sie wenn möglich zur Build-Zeit oder clientseitig nach der Hydration. Static Export funktioniert am besten, wenn das HTML vorab vorbereitet werden kann.

Soll ich .next oder out hochladen?

Für output: 'export' laden Sie out hoch. .next ist ein internes Next.js-Build-Verzeichnis und nicht das statische Export-Artefakt.

Ersetzt das Vercel Next.js Hosting?

Es passt für statische Exporte, nicht für jede Next.js-App. Wenn Sie SSR, Middleware, ISR, Server Actions oder API Routes brauchen, benötigen Sie eine Runtime, die diese Features unterstützt.