Next.js static export

Opublikuj
statyczny Next.js

Wyeksportuj aplikację Next.js do statycznego HTML-a i zasobów, prześlij katalog `out` i opublikuj stronę globalnie bez uruchamiania serwera Node.js.

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

module.exports = nextConfig
Static export włączony

Macierz wsparcia static export

Przed przesłaniem `out` upewnij się, że aplikacja pasuje do modelu statycznego eksportu.

Działa dobrze

  • Trasy statyczne generowane w czasie builda
  • Strony App Router, które mogą być wyrenderowane statycznie
  • Pages Router z getStaticProps / getStaticPaths
  • Pobieranie danych po stronie klienta po hydration
  • next/link, dynamic imports, CSS Modules i statyczne zasoby

Wymaga innego środowiska

  • API routes i route handlers wymagające wykonania na serwerze
  • Middleware, rewrites, redirects i custom headers
  • getServerSideProps oraz renderowanie przy żądaniu
  • Incremental Static Regeneration
  • Domyślna optymalizacja next/image bez statycznej strategii

Użyj Next.js, gdy chcesz framework, ale nie serwer

Zachowaj framework, odłóż serwer

Static export w Next.js pozwala zachować routing plikowy, layouty, metadata, renderowanie w czasie builda, obsługę CSS i klientowego Reacta tam, gdzie jest potrzebny.

Wynik nadal jest zestawem plików. To dobry wybór dla stron marketingowych, dokumentacji, portfolio, stron produktowych, hubów treści i innych widoków, które można przygotować w czasie builda.

Szybkie jak zasób statyczny

Wstępnie wyrenderowany HTML można mocno cache'ować i serwować bez czekania na serwer renderujący.

Mniej utrzymania

Brak środowiska Node oznacza mniej ruchomych części, prostszy artefakt publikacji i mniejsze ryzyko rozjazdu między buildami.

Jasna granica środowiska uruchomieniowego

Jeśli strona potrzebuje kodu serwerowego, nie należy wciskać jej w static export. Jeśli można ją zbudować z wyprzedzeniem, katalog `out` jest czystym artefaktem do publikacji.

Typowe blokery static export

Blocker 01

Build pada przez funkcje serwerowe

Usuń API zależne od żądania z eksportowanej trasy, przenieś je za osobny backend albo opublikuj tę część na platformie ze środowiskiem serwerowym.

Blocker 02

Obrazy działają w devie, ale psują się po eksporcie

Domyślny optymalizator `next/image` oczekuje serwera. Użyj `images.unoptimized`, własnego loadera albo zwykłych statycznych obrazów.

Blocker 03

Brakuje tras dynamicznych

Wygeneruj listę tras w czasie builda przez `generateStaticParams` w App Router albo `getStaticPaths` w Pages Router.

Blocker 04

Redirects albo rewrites nie działają

Przekierowania i rewrites z Next.js nie są częścią static export. Użyj statycznej struktury stron, nawigacji po stronie klienta albo przekierowań platformy, jeśli są dostępne.

Lista kontroli Next.js static export

01

Ustaw output: 'export'

Powiedz Next.js, aby w czasie builda wygenerował statyczny HTML zamiast oczekiwać `next start` albo hostowanego środowiska Node.

output: 'export'
02

Zbuduj i sprawdź /out

Uruchom build produkcyjny i potwierdź, że katalog `out` zawiera wyrenderowane strony, zasoby, stronę 404 i pliki statyczne do publikacji.

npm run build
03

Prześlij i przetestuj trasy

Prześlij katalog `out`, a potem sprawdź zagnieżdżone ścieżki, zasoby statyczne i obrazy nieoptymalizowane w opublikowanej stronie.

FAQ publikacji Next.js

Dlaczego komponent Image w Next.js nie działa po eksporcie?

Domyślny proces optymalizacji obrazów oczekuje serwera. Przy static export ustaw `images.unoptimized` na `true` w `next.config.js`.

Czy API routes albo getServerSideProps działają tutaj?

Nie. Static export usuwa funkcje środowiska serwerowego, takie jak API routes, middleware i `getServerSideProps`. Przenieś tę logikę do osobnego backendu albo usługi serverless.

Czy mogę używać App Router?

Tak, jeśli trasa może być wyrenderowana statycznie i nie zależy od dynamicznych API serwerowych, takich jak `headers` albo `cookies`.

Jak obsłużyć dynamiczną treść?

Pobierz ją w czasie builda, jeśli to możliwe, albo załaduj po stronie klienta po hydration. Static export działa najlepiej, gdy HTML można przygotować wcześniej.

Czy przesłać .next czy out?

Prześlij `out` dla `output: 'export'`. Katalog `.next` jest wewnętrznym folderem builda Next.js i nie jest artefaktem statycznego eksportu do publikacji.

Czy to zastępuje hosting Next.js na Vercel?

To dobry wybór dla statycznych eksportów, nie dla każdej aplikacji Next.js. Jeśli używasz SSR, middleware, ISR, Server Actions albo API routes, potrzebujesz środowiska, które obsługuje te funkcje.