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.