Omgevingsvariabelen in Next.js: .env, NEXT_PUBLIC_ | We.Inc
Hoe Next.js .env-bestanden laadt en in welke volgorde, wat NEXT_PUBLIC_ echt doet tijdens de build en hoe u waarden runtime leest. Plak uw .env om te zien wat de browser bereikt.
Next.js leest .env-bestanden uit de projectroot in process.env. Variabelen zijn standaard alleen voor de server. Zet NEXT_PUBLIC_ voor een naam en Next.js kopieert de waarde tijdens next build naar de browser-JavaScript, waardoor hij openbaar is en vastligt tot u opnieuw bouwt. Zet nooit een geheim achter dat prefix.
Laadvolgorde: het eerste bestand dat een variabele definieert wint
Volgorde
Bron
Opmerkingen
Waarden die de shell of host al heeft gezet winnen altijd
.env.$(NODE_ENV).local
Bijvoorbeeld .env.development.local
.env.local
Overgeslagen als NODE_ENV test is
.env.$(NODE_ENV)
Bijvoorbeeld .env.production
.env
Gedeelde standaardwaarden voor elke omgeving
Plak hieronder de inhoud van een .env-bestand. De checker deelt elke variabele in als alleen server of naar de browser gestuurd, en markeert openbare namen die op geheimen lijken. Hij draait volledig op deze pagina; niets van wat u plakt wordt geüpload.
Plak uw .env-regels in het vak, of bewerk het voorbeeld.
Lees de tabel: elke variabele is gemarkeerd als alleen server of naar de browser gestuurd.
Handel elke waarschuwing af, zoals een NEXT_PUBLIC_-naam met KEY, SECRET of TOKEN erin.
Bouw opnieuw na het wijzigen van een NEXT_PUBLIC_-waarde, want de oude waarde zit ingebakken in de bundle.
Houd .env-bestanden in de projectroot, ook als uw code in een src-map staat. Next.js zoekt er niet naar binnen src.
Commit .env en .env.test met veilige standaardwaarden als uw team dat wil, maar commit nooit .env*.local-bestanden.
Lees openbare variabelen met hun volledige letterlijke naam. process.env[name] of een gedestructureerde process.env wordt tijdens de build niet vervangen.
Eén Docker-image nodig voor staging en productie? Lees servervariabelen tijdens dynamische rendering, en geef alles wat de browser nodig heeft door als props.
Gebruik loadEnvConfig uit @next/env om dezelfde bestanden te laden in een ORM-config, een script of een testsetup buiten Next.js.
Veelgestelde vragen
Waarom is mijn omgevingsvariabele undefined in de browser?
Zonder het prefix NEXT_PUBLIC_ bestaat een variabele alleen op de server, en vervangt Next.js hem in clientcode door een lege string. Voeg het prefix alleen toe als de waarde veilig openbaar mag, en bouw daarna opnieuw.
Ik heb een NEXT_PUBLIC_-waarde bij mijn host gewijzigd en er gebeurde niets. Waarom?
Openbare waarden worden ingevoegd wanneer next build draait. Een gedeployde bundle houdt de oude waarde tot u opnieuw bouwt met de nieuwe.
Werkt .env.local in tests?
Nee. Als NODE_ENV test is, slaat Next.js .env.local over zodat elke testrun dezelfde waarden krijgt. Zet standaardwaarden voor tests in .env.test en persoonlijke overrides in .env.test.local.
Kan de ene variabele naar een andere verwijzen?
Ja. Schrijf $OTHER_NAME in een waarde en Next.js breidt die uit. Heeft de waarde een letterlijk dollarteken nodig, escape het dan als \$.
Waarop staat NODE_ENV?
Als u het niet zet, gebruikt next dev development en gebruiken andere commando's production. De toegestane waarden zijn production, development en test.
Wat NEXT_PUBLIC_ echt doet
Het prefix is een instructie voor de bundler. Tijdens next build wordt elke letterlijke process.env.NEXT_PUBLIC_SOMETHING in uw code vervangen door de waarde uit de omgeving waarin de build draaide, en die tekst belandt in de JavaScript-bestanden die iedereen kan downloaden.
Dat heeft twee gevolgen. Ten eerste is een openbare variabele nooit geheim, hoe het bestand ook heet. Ten tweede ligt hij vast: als u één build van staging naar productie promoveert, gaat de stagingwaarde mee.
Waarden runtime lezen
Servercode kan elke variabele lezen, openbaar of niet. Om zeker te weten dat een waarde per request wordt gelezen in plaats van tijdens de build, rendert u de pagina dynamisch, bijvoorbeeld door connection() uit next/server te awaiten voordat u process.env leest.
De browser kan servervariabelen helemaal niet lezen. Heeft een Client Component een runtimewaarde nodig, haal die dan op via uw eigen Route Handler of geef hem als prop door vanuit een Server Component.
Bescherm tegen lekken
Een helper die een API-key leest, kan per ongeluk in een Client Component worden geïmporteerd. Zet import 'server-only' bovenaan zulke bestanden en de build faalt als een clientbestand ze binnenhaalt.
Variabelen lezen in code
Waarde alleen voor de server in een Route Handler
DB_URL heeft geen prefix, dus bestaat alleen op de server. Route Handlers en Server Components kunnen hem vrij lezen.
Openbare waarde in een Client Component
De volledige letterlijke naam is vereist. Tijdens de build vervangt Next.js hem door de waarde, dus de browser ziet een gewone string.
Een waarde per request lezen
Door connection() te awaiten rendert de pagina dynamisch, zodat de waarde van de draaiende server komt in plaats van uit de build.
loadEnvConfig past dezelfde laadvolgorde toe, waardoor scripts en testsetups gelijk blijven lopen met de app.
.env-checker
Plak .env-regels
Waar elke variabele kan worden gelezen
Variabele
Beschikbaar in
Opmerking
Alleen server
Server en browser (ingevoegd bij de build)
Geen variabeleregel
De naam lijkt op een geheim. Alles met NEXT_PUBLIC_ is zichtbaar voor elke bezoeker.
Verwijst naar {v}, die Next.js uitbreidt.
NODE_ENV accepteert alleen production, development of test.