Variabili d'ambiente in Next.js spiegate

Variabili d'ambiente in Next.js

Variabili d'ambiente in Next.js: .env, NEXT_PUBLIC_ | We.Inc

Come Next.js carica i file .env, in che ordine, cosa fa davvero NEXT_PUBLIC_ in fase di build e come leggere i valori a runtime. Incolla il tuo .env per vedere cosa arriva al browser.

Next.js legge i file .env dalla radice del progetto in process.env. Per impostazione predefinita le variabili sono solo lato server. Aggiungi il prefisso NEXT_PUBLIC_ a un nome e Next.js ne copia il valore nel JavaScript del browser durante next build, quindi diventa pubblico e resta fisso finché non ricompili. Non mettere mai un segreto dietro quel prefisso.

Ordine di caricamento: vince il primo file che definisce una variabile

  • Ordine
  • Fonte
  • Note
  • I valori già impostati dalla shell o dall'host vincono sempre
  • .env.$(NODE_ENV).local
  • Ad esempio .env.development.local
  • .env.local
  • Saltato quando NODE_ENV è test
  • .env.$(NODE_ENV)
  • Ad esempio .env.production
  • .env
  • Valori predefiniti condivisi per ogni ambiente

Incolla qui sotto il contenuto di un file .env. Il controllo classifica ogni variabile come solo server o inviata al browser, e segnala i nomi pubblici che sembrano segreti. Funziona interamente in questa pagina; nulla di ciò che incolli viene caricato.

  • Incolla le righe del tuo .env nella casella, oppure modifica l'esempio.
  • Leggi la tabella: ogni variabile è indicata come solo server o inviata al browser.
  • Intervieni su ogni avviso, ad esempio un nome NEXT_PUBLIC_ che contiene KEY, SECRET o TOKEN.
  • Ricompila dopo aver cambiato un valore NEXT_PUBLIC_, perché il vecchio valore è incorporato nel bundle.
  • Tieni i file .env nella radice del progetto, anche quando il codice sta in una cartella src. Next.js non li cerca dentro src.
  • Fai commit di .env e .env.test con valori predefiniti sicuri se il tuo team li vuole, ma non fare mai commit dei file .env*.local.
  • Leggi le variabili pubbliche con il loro nome letterale completo. process.env[name] o un process.env destrutturato non vengono sostituiti in fase di build.
  • Ti serve un'unica immagine Docker per staging e produzione? Leggi le variabili server durante il rendering dinamico, e passa come prop tutto ciò che serve al browser.
  • Usa loadEnvConfig da @next/env per caricare gli stessi file nella configurazione di un ORM, in uno script o in un setup di test fuori da Next.js.

Domande frequenti

Perché la mia variabile d'ambiente è undefined nel browser?

Senza il prefisso NEXT_PUBLIC_ una variabile esiste solo sul server, e Next.js la sostituisce con una stringa vuota nel codice client. Aggiungi il prefisso solo se il valore può essere pubblicato senza rischi, poi ricompila.

Ho cambiato un valore NEXT_PUBLIC_ sul mio host e non è successo nulla. Perché?

I valori pubblici vengono incorporati quando viene eseguito next build. Un bundle già distribuito mantiene il vecchio valore finché non ricompili con quello nuovo.

.env.local funziona nei test?

No. Quando NODE_ENV è test, Next.js salta .env.local così ogni esecuzione dei test riceve gli stessi valori. Metti i valori predefiniti per i test in .env.test e gli override personali in .env.test.local.

Una variabile può fare riferimento a un'altra?

Sì. Scrivi $OTHER_NAME dentro un valore e Next.js lo espande. Se il valore richiede un simbolo del dollaro letterale, esegui l'escape come \$.

Che valore ha NODE_ENV?

Se non lo imposti, next dev usa development e gli altri comandi usano production. I valori consentiti sono production, development e test.

Cosa fa davvero NEXT_PUBLIC_

  • Il prefisso è un'istruzione per il bundler. Durante next build, ogni process.env.NEXT_PUBLIC_SOMETHING letterale nel tuo codice viene sostituito con il valore dell'ambiente in cui è avvenuta la build, e quel testo finisce nei file JavaScript che chiunque può scaricare.
  • Questo ha due conseguenze. Primo, una variabile pubblica non è mai segreta, comunque si chiami il file. Secondo, è congelata: promuovere una build da staging a produzione porta con sé il valore di staging.

Leggere i valori a runtime

  • Il codice server può leggere qualsiasi variabile, pubblica o no. Per assicurarti che un valore venga letto a ogni richiesta e non in fase di build, renderizza la pagina in modo dinamico, ad esempio facendo await di connection() da next/server prima di leggere process.env.
  • Il browser non può leggere affatto le variabili server. Se un Client Component ha bisogno di un valore a runtime, recuperalo da un tuo Route Handler o passalo come prop da un Server Component.

Proteggersi dalle fughe di dati

  • Un helper che legge una chiave API può essere importato per errore in un Client Component. Aggiungi import 'server-only' in cima a questi file e la build fallisce se un file client li importa.

Leggere le variabili nel codice

Valore solo server in un Route Handler

DB_URL non ha prefisso, quindi esiste solo sul server. Route Handlers e Server Components possono leggerlo liberamente.

Valore pubblico in un Client Component

Serve il nome letterale completo. In fase di build Next.js lo sostituisce con il valore, quindi il browser vede una semplice stringa.

Leggere un valore a ogni richiesta

Fare await di connection() rende la pagina dinamica, quindi il valore arriva dal server in esecuzione invece che dalla build.

loadEnvConfig applica lo stesso ordine di caricamento, il che mantiene script e setup di test allineati con l'app.

Controllo .env

Incolla le righe del .env

Dove può essere letta ogni variabile

Variabile

Disponibile in

Nota

Solo server

Server e browser (incorporata in fase di build)

Non è una riga di variabile

Il nome sembra un segreto. Tutto ciò che ha NEXT_PUBLIC_ è visibile a ogni visitatore.

Fa riferimento a {v}, che Next.js espande.

NODE_ENV accetta solo production, development o test.

Nessuna variabile trovata per ora.

{n} solo server, {v} inviate al browser

Crea il tuo sito gratis · Gratis per creare, senza carta

Correlati: Guide

Prodotto

Per chi è

Funzionalità

Risorse

Azienda

Mappa del sito