Vercel: miljövariabler utan .env i Git

Den här guiden är avsedd för ett projekt som redan finns på Vercel. Du behöver åtkomst till dess inställningar och förstå vilka variabler programmet läser. Exemplet nedan gäller Next.js; variabelnamn från ett annat ramverk kan inte överföras automatiskt. Guiden bygger på officiell dokumentation; den har inte testats på ett verkligt konto.

Praktisk information om hur du använder Ailoot finns i dokumentationen.

Varför du inte behöver lägga till .env i Git#

En miljövariabel är en inställning med ett namn och ett värde som ett program får separat från sin källkod. Till exempel ger namnet SERVICE_API_KEY programmet åtkomst till värdet för en extern tjänsts nyckel. Lägg inte själva nyckeln i guiden, i din konversation med en agent eller i kodförrådet.

Next.js kan läsa in variabler från lokala .env*-filer. En lokal fil och ett projekts inställningar i Vercel är dock två separata platser. Om filen inte skickas till kodförrådet ställer du in värdena separat på värdplattformen. Standardmallen create-next-app lägger till .env-filer i .gitignore; Next.js-dokumentationen varnar för att du nästan aldrig bör skicka dem till kodförrådet.

Om du fortfarande är osäker på vad som kan lagras i källfiler kan du börja med säkerhetskontrollen för ett projekt byggt med AI. Här tar vi upp en mer avgränsad fråga: var du ställer in konfigurationen för en viss Vercel-driftsättning.

Ta först reda på var programmet läser variabeln#

Gör en lista över namn innan du anger några värden, utan själva hemligheterna. För varje namn behöver du ta reda på tre saker: vilken miljö som använder det, var koden som läser variabeln körs och när värdet behövs.

Miljön Development är avsedd för lokal utveckling. Preview gäller förhandsvisningsdriftsättningar och Production gäller den huvudsakliga publicerade versionen. Preview kan ha inställningar för en viss Git-gren: de åsidosätter de allmänna Preview-inställningarna med samma namn.

I ett Next.js-projekt är variabler utan NEXT_PUBLIC_ som standard tillgängliga på servern. Prefixet NEXT_PUBLIC_ gör att värdet kan bäddas in i JavaScript som skickas till webbläsaren. Det passar för en inställning som uttryckligen är offentlig, till exempel en versionsetikett som inte är hemlig, men inte för en privat API-nyckel. Även utan detta prefix får programkoden inte manuellt skicka en hemlighet till klienten.

Om du ännu inte har identifierat ramverket ber du agenten att identifiera det utifrån projektfilerna. Jämförelsen mellan Astro och Next.js kan hjälpa dig att förstå skillnaderna; regeln för NEXT_PUBLIC_ gäller inte alla React-program.

Värdkonfiguration är en av uppgifterna när du arbetar med ett program med hjälp av en AI-agent.

Så lägger du till en variabel i ett Vercel-projekt#

Utför stegen själv i den officiella kontrollpanelen. Ge inte agenten en riktig nyckel för att fylla i formuläret och bifoga inte en skärmbild som visar dess värde.

1. Öppna Vercels kontrollpanel och välj rätt projekt. Förlita dig inte enbart på att kodförrådet har ett namn som verkar stämma: kontrollera att du konfigurerar programmet som du tänker öppna.
2. Gå till Environment Variables i sidomenyn för projektinställningarna.
3. Ange namnet som programmet läser i fältet Name, till exempel SERVICE_API_KEY. Det här är ett exempel på ett namn; om koden förväntar sig ett annat använder du exakt den stavningen.
4. Ange värdet från din inloggningsuppgiftshanterare i fältet Value. Lägg det inte i källkoden, en chatt eller en verifieringslogg.
5. Välj den miljö som behöver den här inställningen. Använd Preview för att kontrollera en förhandsvisningsversion och Production för huvudversionen. Tilldela inte automatiskt samma hemlighet till alla miljöer.
6. Om Preview-inställningen gäller en viss gren kontrollerar du den valda grenen och eventuella åsidosättningar med samma namn.
7. Klicka på Save.

Vercel gör projektvariabler tillgängliga både under bygget och när Vercel Functions körs på serversidan. Att ett värde är tillgängligt i Vercel betyder dock inte att det kan skickas till webbläsaren: det beror på programmets kod och ramverkets regler.

Varför du behöver en ny driftsättning efter att du klickat på Save#

Att spara en variabel ändrar inte befintliga driftsättningar. Enligt Vercels dokumentation måste du driftsätta projektet igen för att den nya inställningen ska nå den version du använder.

När du arbetar via Git kan du skapa en ny Production-driftsättning genom att skicka en commit till grenen som anges under Production Branch, och en Preview-driftsättning genom att skicka till en annan gren. Utgå inte från att huvudgrenen alltid heter main: kontrollera projektets inställning. Detta ska vara en vanlig, överenskommen projektversion, utan att någon hemlig fil läggs till i committen.

När du har startat driftsättningen väntar du tills bygget är klart och öppnar URL:en för den nya driftsättningen. Anteckna dess URL, miljö och gren. Om du kontrollerar den gamla URL:en till en enskild driftsättning visas inte de nya inställningarna där.

Next.js har ytterligare ett villkor: referenser som process.env.NEXT_PUBLIC_RELEASE_LABEL ersätts med sina värden under next build. Värdet är fast efter bygget. Om du ändrar inställningen utan ett nytt bygge skrivs JavaScript för klientsidan som redan har skickats ut inte om.

Så kontrollerar du resultatet utan att röja nyckeln#

Börja med ett säkert exempel: en uttryckligen icke-hemlig etikett med namnet NEXT_PUBLIC_RELEASE_LABEL och värdet preview-check. Det här är ett exempel på ett namn och en text, inte en nyckel eller ett test som utförts här. Om ett Next.js-program läser variabeln direkt via process.env.NEXT_PUBLIC_RELEASE_LABEL kan det visa etiketten på avsedd plats i gränssnittet efter ett nytt bygge. Den här kontrollen bekräftar endast att den offentliga inställningen fördes vidare.

En privat nyckel kontrolleras på ett annat sätt. Skriv inte ut dess värde, en del av det, dess längd eller hela process.env. Skapa inte en offentlig URL som returnerar variabelns innehåll. Kontrollera först endast om inställningen är ”angiven / saknas” på servern och kontrollera sedan separat programfunktionen som använder tjänsten. Att en inställning finns bevisar inte att nyckeln är giltig eller har de behörigheter som krävs.

Du kan dokumentera resultaten utan hemligheter:

• projektet, miljön och grenen stämmer med dem du valde vid konfigurationen;
• du kontrollerar URL:en till en ny driftsättning som skapades efter att variabeln sparades;
• bygget är klart och den programfunktion som behövs har körts med säkra testdata;
• hemligheten exponeras inte i webbläsaren, API-svar, loggar eller konversationer.

Om funktionen gör en betalning, skickar ett meddelande eller utför någon annan handling med konsekvenser använder du tjänstens avsedda testläge. Att kontrollera konfigurationen ger inte i sig tillstånd att utföra en verklig åtgärd.

Vad du ska kontrollera om värdet fortfarande är undefined#

undefined betyder att inget värde hämtades på den platsen där åtkomsten skedde. Kontrollera namn, miljö och version i tur och ordning utan att ändra alla inställningar samtidigt.

När du har kontrollerat namnet, miljön och den nya versionen bevisar ett fel i funktionen fortfarande inte att variabeln orsakade det. Undersök det specifika felet i serverkoden utan att publicera diagnostiska uppgifter som innehåller hemligheter. Den här guiden utlovar inte att lösa alla HTTP 500-svar.

Om du flyttar till en egen server behöver du en annan procedur: se guiden till att driftsätta ett projekt med Coolify. Vercels knappnamn och konfigurationssteg gäller inte där.

Gå till Ailoot.