Esportazione statica Next.js

Pubblica
siti statici Next.js

Esporta la tua app Next.js in HTML statico e asset, carica la directory out e pubblicala a livello globale senza eseguire un server Node.js.

Consulta la guida alla configurazione
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
// Optional for static deployments
images: { unoptimized: true },
}

module.exports = nextConfig
Esportazione statica abilitata

Matrice di supporto per l'export statico

Prima di caricare out, assicurati che l'app sia adatta al modello di export statico.

Funziona bene

  • Route statiche generate in fase di build
  • Pagine App Router renderizzabili staticamente
  • Pagine Router getStaticProps / getStaticPaths
  • Data fetching lato client dopo l'hydration
  • next/link, dynamic imports, CSS Modules e asset statici

Ha bisogno di un altro runtime

  • API routes e route handlers che richiedono esecuzione server
  • Middleware, rewrites, redirects e custom headers
  • getServerSideProps e request-time rendering
  • Rigenerazione statica incrementale
  • Ottimizzazione next/image predefinita senza una strategia statica personalizzata

Usa Next.js quando vuoi il framework, non il server

Mantieni il framework, rilascia il server

L'export statico di Next.js ti consente di mantenere routing basato su file, layout, metadata, rendering in fase di build, supporto CSS e React lato client dove serve.

L'output resta un insieme di file. Per questo funziona bene per siti marketing, documentazione, portfolio, pagine prodotto, hub di contenuti e altre pagine che possono essere preparate durante la build.

Veloce come un asset statico

L'HTML pre-renderizzato può essere messo in cache in modo aggressivo e servito direttamente dalla rete globale senza attendere un server di rendering.

Meno overhead operativo

Senza runtime Node.js ci sono meno parti mobili, artefatti di deploy più semplici e meno differenze tra build e produzione.

Confine runtime chiaro

Se una pagina richiede codice server, non va forzata nell'export statico. Se può essere generata in anticipo, la directory out è un artefatto pulito da pubblicare.

Blocchi comuni dello static export

Blocker 01

La build fallisce per funzionalità solo server

Rimuovi le API request-time dalla route esportata, spostale dietro un backend separato o pubblica quella parte su una piattaforma con runtime server.

Blocker 02

Le immagini funzionano in fase di sviluppo ma falliscono dopo l'esportazione

L'ottimizzatore next/image predefinito prevede un server. Usa images.unoptimized, un loader personalizzato o normali asset immagine statici.

Blocker 03

Mancano route dinamiche

Genera l'elenco delle route in fase di build con generateStaticParams nell'App Router o getStaticPaths nel Pages Router.

Blocker 04

Redirects o rewrites non vengono applicati

Redirects e rewrites di Next.js non fanno parte dello static export. Usa una struttura di pagine statiche, navigazione lato client o redirect a livello di piattaforma, quando disponibili.

Checklist per Next.js static export

01

Imposta output: 'export'

Dì a Next.js di emettere HTML statico in fase di build invece di aspettarsi next start o un runtime Node.js ospitato.

output: 'export'
02

Esegui la build e verifica /out

Esegui la build di produzione e verifica che la directory out contenga le pagine renderizzate, gli asset, la pagina 404 e i file statici che prevedi di pubblicare.

npm run build
03

Carica e testa le route

Carica la directory out, quindi controlla route annidate, asset statici e immagini non ottimizzate nel sito pubblicato.

Domande frequenti sulla pubblicazione di Next.js

Perché il componente Image di Next.js non funziona dopo l'export?

La pipeline predefinita di image optimization richiede un server. Per static export, imposta images.unoptimized su true in next.config.js.

API routes o getServerSideProps funzionano qui?

No. Static export rimuove funzionalità runtime lato server come API routes, middleware e getServerSideProps. Sposta quella logica su un backend separato o su un servizio serverless.

Posso utilizzare l'App Router?

Sì, purché la route possa essere renderizzata in modo statico e non dipenda da API dinamiche solo server come headers o cookies.

Come devo gestire i contenuti dinamici?

Recupera i dati in fase di build quando possibile, oppure caricali lato client dopo l'hydration della pagina. Static export funziona meglio quando l'HTML può essere preparato in anticipo.

Devo caricare .next o out?

Carica out per output: 'export'. La directory .next è una directory di build interna di Next.js e non è l'artefatto di export statico che vuoi pubblicare.

Si tratta di un sostituto dell'hosting Vercel Next.js?

È adatto per le esportazioni statiche, non per tutte le app Next.js. Se ti affidi a SSR, middleware, ISR, azioni server o percorsi API, hai bisogno di un runtime che supporti tali funzionalità.