Vercel: Miljøvariabler uden .env i Git

Denne vejledning er til et projekt, der allerede er hostet på Vercel. Du skal have adgang til dets indstillinger og vide, hvilke variabler programmet læser. Eksemplet nedenfor gælder Next.js; variabelnavne fra et andet framework kan ikke automatisk overføres. Vejledningen er baseret på officiel dokumentation; den er ikke blevet afprøvet på en rigtig konto.

Praktisk information om brug af Ailoot findes i dokumentationen.

Hvorfor du ikke behøver at føje .env til Git#

En miljøvariabel er en indstilling med et navn og en værdi, som et program modtager separat fra sin kildekode. For eksempel giver navnet SERVICE_API_KEY programmet adgang til værdien af en ekstern tjenestes nøgle. Skriv ikke selve nøglen i vejledningen, i din samtale med en agent eller i repository'et.

Next.js kan indlæse variabler fra lokale .env*-filer. En lokal fil og et projekts indstillinger i Vercel er dog to separate placeringer. Hvis filen ikke bliver sendt til repository'et, skal du indstille værdierne separat på hostingplatformen. Standardskabelonen create-next-app føjer .env-filer til .gitignore; Next.js-dokumentationen advarer om, at du næsten aldrig bør sende dem til repository'et.

Hvis du stadig er usikker på, hvad der kan gemmes i kildefiler, kan du begynde med sikkerhedstjekket for et projekt bygget med AI. Her behandler vi et mere afgrænset spørgsmål: hvor du angiver konfigurationen for en bestemt Vercel-udrulning.

Find først ud af, hvor programmet læser variablen#

Lav en liste over navne, før du indtaster værdier, uden selve hemmelighederne. For hvert navn skal du fastslå tre ting: hvilket miljø der bruger det, hvor koden, som læser variablen, kører, og hvornår værdien er nødvendig.

Miljøet Development er beregnet til lokal udvikling. Preview er til forhåndsvisningsudrulninger, og Production er til den primære publicerede version. Preview kan have indstillinger for en bestemt Git-branch: de tilsidesætter de generelle Preview-indstillinger med samme navne.

I et Next.js-projekt er variabler uden NEXT_PUBLIC_ som standard tilgængelige på serveren. Præfikset NEXT_PUBLIC_ gør det muligt at indlejre værdien i den JavaScript-kode, der leveres til browseren. Det egner sig til en indstilling, der udtrykkeligt er offentlig, såsom en ikke-hemmelig versionsetiket, men ikke til en privat API-nøgle. Selv uden dette præfiks må programkoden ikke manuelt sende en hemmelighed til klienten.

Hvis du endnu ikke har identificeret frameworket, kan du bede agenten om at identificere det ud fra projektfilerne. Sammenligningen af Astro og Next.js kan hjælpe dig med at forstå forskellene; reglen om NEXT_PUBLIC_ gælder ikke for alle React-programmer.

Hostingkonfiguration er en af opgaverne i arbejdet med et program ved hjælp af en AI-agent.

Sådan føjer du en variabel til et Vercel-projekt#

Udfør selv trinnene i det officielle dashboard. Giv ikke agenten en rigtig nøgle, så den kan udfylde formularen, og vedhæft ikke et skærmbillede, der viser dens værdi.

1. Åbn Vercels dashboard, og vælg det rigtige projekt. Stol ikke alene på, at repository'et har et navn, der matcher: kontrollér, at du konfigurerer det program, du har tænkt dig at åbne.
2. Gå til Environment Variables i sidepanelet med projektindstillinger.
3. Indtast det navn, programmet læser, i Name, for eksempel SERVICE_API_KEY. Dette er et eksempel på et navn; hvis koden forventer et andet, skal du bruge den nøjagtige stavemåde.
4. Indtast værdien fra dit legitimationsoplysningslager i Value. Skriv den ikke i kildekoden, en chat eller en verifikationslog.
5. Vælg det miljø, der har brug for denne indstilling. Brug Preview til at kontrollere en forhåndsvisningsversion og Production til hovedversionen. Tildel ikke automatisk den samme hemmelighed til alle miljøer.
6. Hvis Preview-indstillingen gælder for en bestemt branch, skal du kontrollere den valgte branch og eventuelle tilsidesættelser med samme navn.
7. Klik på Save.

Vercel gør projektvariabler tilgængelige både under buildet og når serverbaserede Vercel Functions kører. Men at en værdi er tilgængelig i Vercel, betyder ikke, at den kan sendes til browseren: det afhænger af programkoden og frameworkets regler.

Hvorfor du har brug for en ny udrulning efter at have klikket på Save#

Når du gemmer en variabel, ændres eksisterende udrulninger ikke. Vercels dokumentation kræver, at du udruller projektet igen, før den nye indstilling når frem til den version, du bruger.

Når du arbejder via Git, kan du oprette en ny Production-udrulning ved at pushe en commit til den branch, der er angivet under Production Branch, og en Preview-udrulning ved at pushe til en anden branch. Antag ikke, at hovedbranchen altid hedder main: kontrollér indstillingen for dit projekt. Det skal være en almindelig, aftalt projektudgivelse uden at føje en hemmelig fil til committen.

Når du har startet udrulningen, skal du vente, til buildet er færdigt, og åbne URL'en til den nye udrulning. Notér dens URL, miljø og branch. Hvis du kontrollerer den gamle URL til en enkelt udrulning, vises de nye indstillinger ikke dér.

Next.js har en yderligere betingelse: referencer som process.env.NEXT_PUBLIC_RELEASE_LABEL erstattes med deres værdier under next build. Værdien er fast efter buildet. Hvis du ændrer indstillingen uden et nyt build, bliver JavaScript-kode på klientsiden, som allerede er blevet leveret, ikke skrevet om.

Sådan kontrollerer du resultatet uden at afsløre nøglen#

Begynd med et sikkert eksempel: en udtrykkeligt ikke-hemmelig etiket med navnet NEXT_PUBLIC_RELEASE_LABEL og værdien preview-check. Dette er et eksempel på et navn og en tekst, ikke en nøgle eller en test, der er udført her. Hvis et Next.js-program læser denne variabel direkte via process.env.NEXT_PUBLIC_RELEASE_LABEL, kan det vise etiketten det tilsigtede sted i brugerfladen efter et nyt build. Denne kontrol bekræfter kun, at den offentlige indstilling blev overført.

En privat nøgle kontrolleres på en anden måde. Udskriv ikke dens værdi, en del af den, dens længde eller hele process.env. Opret ikke en offentlig URL, der returnerer variablens indhold. Kontrollér først kun, om indstillingen er “til stede / fraværende” på serveren, og kontrollér derefter separat programfunktionen, der bruger tjenesten. At en indstilling er til stede, beviser ikke, at nøglen er gyldig eller har de nødvendige tilladelser.

Du kan registrere resultaterne uden hemmeligheder:

• projektet, miljøet og branchen stemmer overens med dem, der blev valgt under konfigurationen;
• du kontrollerer URL'en til en ny udrulning, som blev oprettet efter at variablen blev gemt;
• buildet er færdigt, og den nødvendige programfunktion er blevet kørt med sikre testdata;
• hemmeligheden afsløres ikke i browseren, API-svar, logfiler eller samtaler.

Hvis funktionen foretager en betaling, sender en besked eller udfører en anden handling med konsekvenser, skal du bruge tjenestens angivne testtilstand. Kontrol af konfigurationen giver ikke i sig selv tilladelse til en handling i det virkelige system.

Hvad du skal kontrollere, hvis værdien stadig er undefined#

undefined betyder, at der ikke blev hentet nogen værdi på det pågældende adgangssted. Gennemgå navn, miljø og version i rækkefølge uden at ændre alle indstillinger på én gang.

Når du har kontrolleret navnet, miljøet og den nye version, beviser en fejl i funktionen stadig ikke, at variablen forårsagede den. Undersøg den konkrete fejl i serverkoden uden at offentliggøre diagnostiske data, der indeholder hemmeligheder. Denne vejledning lover ikke at løse alle HTTP 500-svar.

Det kræver en anden fremgangsmåde at flytte til din egen server: se vejledningen til udrulning af et projekt med Coolify. Vercels knapnavne og konfigurationstrin gælder ikke dér.

Gå til Ailoot.