Vercel: omgevingsvariabelen zonder .env in Git

Deze handleiding is bedoeld voor een project dat al op Vercel wordt gehost. Je hebt toegang nodig tot de instellingen en moet weten welke variabelen de applicatie leest. Het onderstaande voorbeeld geldt voor Next.js; variabelenamen van een ander framework kunnen niet automatisch worden overgenomen. De handleiding is gebaseerd op officiële documentatie en is niet getest met een echt account.

Praktische informatie over het gebruik van Ailoot vind je in de documentatie.

Waarom je .env niet aan Git hoeft toe te voegen#

Een omgevingsvariabele is een instelling met een naam en een waarde die een applicatie los van de broncode ontvangt. Met de naam SERVICE_API_KEY kan het programma bijvoorbeeld de waarde van een sleutel voor een externe dienst gebruiken. Zet de sleutel zelf niet in de handleiding, in gesprekken met een agent of in de repository.

Next.js kan variabelen laden uit lokale .env*-bestanden. Een lokaal bestand en de projectinstellingen in Vercel zijn echter twee afzonderlijke locaties. Als het bestand niet naar de repository wordt gepusht, stel je de waarden afzonderlijk in op het hostingplatform. De standaardtemplate van create-next-app voegt .env-bestanden toe aan .gitignore; de Next.js-documentatie waarschuwt dat je ze vrijwel nooit naar de repository moet pushen.

Weet je nog niet zeker wat je in bronbestanden kunt opslaan, begin dan met de beveiligingscontrole voor een project dat met AI is gebouwd. Hier behandelen we een beperktere vraag: waar je de configuratie instelt voor een specifieke Vercel-deployment.

Bepaal eerst waar de applicatie de variabele leest#

Maak voordat je waarden invoert een lijst met namen, zonder de geheimen zelf. Voor elke naam moet je drie dingen vaststellen: welke omgeving de variabele gebruikt, waar de code die de variabele leest wordt uitgevoerd en wanneer de waarde nodig is.

De omgeving Development is bedoeld voor lokale ontwikkeling. Preview is voor preview-deployments en Production voor de belangrijkste gepubliceerde versie. Preview kan instellingen hebben voor een specifieke Git-branch: deze overschrijven de algemene Preview-instellingen met dezelfde naam.

In een Next.js-project zijn variabelen zonder NEXT_PUBLIC_ standaard beschikbaar op de server. Met het voorvoegsel NEXT_PUBLIC_ kan de waarde worden opgenomen in de JavaScript-code die aan de browser wordt geleverd. Dit is geschikt voor een instelling die nadrukkelijk openbaar is, zoals een niet-geheim versielabel, maar niet voor een privésleutel voor een API. Ook zonder dit voorvoegsel mag applicatiecode een geheim niet handmatig aan de client retourneren.

Heb je het framework nog niet vastgesteld, vraag de agent dan om het aan de hand van de projectbestanden te identificeren. De vergelijking van Astro en Next.js kan je helpen de verschillen te begrijpen; de regel voor NEXT_PUBLIC_ geldt niet voor elke React-applicatie.

Hostingconfiguratie is een van de taken die komen kijken bij het werken aan een applicatie met een AI-agent.

Een variabele toevoegen aan een Vercel-project#

Voer de stappen zelf uit in het officiële dashboard. Geef de agent geen echte sleutel om het formulier in te vullen en voeg geen screenshot toe waarop de waarde te zien is.

1. Open het Vercel-dashboard en selecteer het juiste project. Vertrouw niet alleen op een overeenkomende repositorynaam: controleer of je de applicatie configureert die je wilt openen.
2. Ga in de zijbalk met projectinstellingen naar Environment Variables.
3. Voer bij Name de naam in die de applicatie leest, zoals SERVICE_API_KEY. Dit is een voorbeeldnaam; verwacht de code een andere naam, gebruik dan exact die schrijfwijze.
4. Voer bij Value de waarde uit je opslag voor inloggegevens in. Zet deze niet in de broncode, een chat of een verificatielogboek.
5. Selecteer de omgeving waarvoor deze instelling nodig is. Gebruik Preview om een previewversie te controleren en Production voor de hoofdversie. Wijs één geheim niet automatisch aan alle omgevingen toe.
6. Is de Preview-instelling van toepassing op een specifieke branch, controleer dan de geselecteerde branch en eventuele overschrijving met dezelfde naam.
7. Klik op Save.

Vercel maakt projectvariabelen beschikbaar tijdens de build en wanneer Vercel Functions aan de serverzijde worden uitgevoerd. Dat een waarde binnen Vercel beschikbaar is, betekent echter niet dat deze naar de browser mag worden verstuurd: dat hangt af van de applicatiecode en de regels van het framework.

Waarom je na Save een nieuwe deployment nodig hebt#

Een variabele opslaan verandert bestaande deployments niet. Volgens de Vercel-documentatie moet je het project opnieuw deployen om de nieuwe instelling beschikbaar te maken in de versie die je gebruikt.

Werk je via Git, dan kun je een nieuwe Production-deployment maken door een commit te pushen naar de branch die bij Production Branch is opgegeven, en een Preview-deployment door naar een andere branch te pushen. Ga er niet van uit dat de hoofdbranch altijd main heet: controleer de instelling van je project. Dit hoort een normale, afgesproken projectrelease te zijn, zonder een geheim bestand aan de commit toe te voegen.

Wacht nadat de deployment is gestart tot de build klaar is en open de URL van de nieuwe deployment. Noteer de URL, omgeving en branch. Controleer je de oude URL van een afzonderlijke deployment, dan zijn de nieuwe instellingen daar niet zichtbaar.

In Next.js geldt nog een voorwaarde: verwijzingen zoals process.env.NEXT_PUBLIC_RELEASE_LABEL worden tijdens next build vervangen door hun waarden. De waarde ligt vast nadat de build is uitgevoerd. Als je de instelling wijzigt zonder een nieuwe build te maken, wordt eerder geleverde JavaScript aan de clientzijde niet aangepast.

Het resultaat controleren zonder de sleutel bloot te leggen#

Begin met een veilig voorbeeld: een expliciet niet-geheim label met de naam NEXT_PUBLIC_RELEASE_LABEL en de waarde preview-check. Dit zijn een voorbeeldnaam en tekst, geen sleutel en ook geen test die hier is uitgevoerd. Leest een Next.js-applicatie deze variabele rechtstreeks via process.env.NEXT_PUBLIC_RELEASE_LABEL, dan kan de applicatie het label na een nieuwe build op de beoogde plek in de interface weergeven. Deze controle bevestigt alleen dat de openbare instelling is doorgegeven.

Een privésleutel controleer je op een andere manier. Geef de waarde, een deel ervan, de lengte ervan of de volledige process.env niet weer. Maak geen openbare URL die de inhoud van de variabele retourneert. Controleer eerst alleen of de instelling aan de serverzijde “aanwezig / afwezig” is en controleer daarna afzonderlijk de applicatiefunctie die de dienst gebruikt. Dat een instelling aanwezig is, bewijst niet dat de sleutel geldig is of de vereiste rechten heeft.

Je kunt de resultaten zonder geheimen vastleggen:

• het project, de omgeving en de branch komen overeen met de selectie tijdens de configuratie;
• je controleert de URL van een nieuwe deployment die is gemaakt nadat je de variabele hebt opgeslagen;
• de build is klaar en de vereiste applicatiefunctie is uitgevoerd met veilige testgegevens;
• het geheim is niet blootgelegd in de browser, API-responses, logboeken of gesprekken.

Voert de functie een betaling uit, verstuurt die een bericht of heeft een andere handeling gevolgen, gebruik dan de aangewezen testmodus van de dienst. De configuratie controleren geeft op zichzelf geen toestemming voor een echte handeling.

Wat je moet controleren als de waarde nog steeds undefined is#

undefined betekent dat er op dat toegangspunt geen waarde is verkregen. Controleer achtereenvolgens de naam, omgeving en versie, zonder alle instellingen tegelijk te wijzigen.

Heb je de naam, omgeving en nieuwe versie gecontroleerd, dan bewijst een fout in de functie nog steeds niet dat de variabele de oorzaak is. Onderzoek de specifieke fout in de code aan de serverzijde zonder diagnostische gegevens met geheimen te publiceren. Deze handleiding belooft niet elke HTTP 500-respons op te lossen.

Overstappen naar je eigen server vereist een andere procedure: zie de handleiding voor het deployen van een project met Coolify. De knopnamen en configuratiestappen van Vercel zijn daarop niet van toepassing.

Ga naar Ailoot.