Omgevingsvariabelen

Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…

Omgevingsvariabelen bevatten de configuratie en geheimen die uw app nodig heeft tijdens het bouwen en tijdens runtime, zoals API-sleutels, database-URL's en feature flags, zonder dat iets hiervan in uw repository opgeslagen is. Deze handleiding behandelt waar ze zich bevinden in Orbit, hoe bereik en prioriteit werken, een waarde als geheim markeren, bulkimport en export, en de fouten die ertoe leiden dat een variabele op de een of andere manier altijd ongedefinieerd is.

Waar Ze Zich Bevinden

Open uw project in Orbit en klik op het tabblad Env vars, op /orbit/<project-id>/env-vars.

De pagina is ingedeeld in secties:

All environments bovenaan: projectbrede variabelen, beschikbaar in elke build.
Een inklapbare sectie per omgeving (Production, Staging en eventuele previews) met de overschrijvingen van die omgeving.

Boven de lijst staat een zoekvak en een filter Secrets only, wat de snelle manier is om een lange lijst door te gaan.

Hoe Bereik Werkt

Bereik	Wat het beïnvloedt
All environments (projectbrede)	Ingespoten in elke build van dit project
Environment-level override	Geldt alleen voor die ene omgeving en wint van de projectbrede waarde met dezelfde sleutel

De ondertitel op de pagina stelt de regel duidelijk: projectbrede variabelen zijn beschikbaar in elke build, en environment-level overschrijvingen hebben voorrang.

Een typische setup is een projectbrede DATABASE_URL die naar een testdatabase wijst, met een override op productieniveau die naar de echte wijst. Productiebuilds krijgen de echte database, alles ander krijgt de testdatabase, en niets wat u later toevoegt lekt per ongeluk de productiereferenties in een preview.

Er is ook een besturingselement Available in op projectbrede variabelen, waarmee u bepaalde omgevingstypen kunt uitsluiten (production, staging, preview) van een variabele die anders projectbrede is.

Volledige details over per-environment scoping, inclusief de beveiligingsredenen, vindt u in Omgevingsvariabelen Per Omgeving Instellen.

Een projectbrede variabele wordt ingespoten in branch preview-builds, en preview-URL's zijn publiekelijk bereikbaar voor iedereen met de link. Productiedatabasereferenties, live betalingssleutels en beheerdertoken moeten alleen voor productie gelden. Dit is het enige meest impactvolle ding om goed op deze pagina in te stellen.

Een Variabele Toevoegen

Scroll naar het formulier Add variable onderaan het tabblad Env vars.
Voer de KEY in, bijvoorbeeld NEXT_PUBLIC_API_URL.
Voer de value in.
Kies een Scope: All environments (project-wide), of een specifieke environment override.
Als u project-wide koos, gebruikt u de knoppen Available in om alle omgevingstypen af te selecteren waarvoor deze variabele niet beschikbaar mag zijn.
Vink Mark as secret aan voor alles wat gevoelig is.
Klik op Add.

Het formulier vertelt u wat het gaat doen voordat u zich vastlegt: een environment override toont een melding dat deze alleen van toepassing is op de builds van die omgeving, en een beperkte projectbrede variabele toont in welke omgevingstypen deze wordt ingespoten.

Wanneer Wijzigingen Van Kracht Worden

Het toevoegen, bewerken of verwijderen van een variabele verandert de deployment die momenteel live is niet. Variabelen worden ingespoten wanneer een build wordt uitgevoerd, dus de wijziging is van toepassing vanaf de next deployment. Redeploy nadat u iets hebt gewijzigd waar uw app van afhangt.

Orbit is hier duidelijk over. Open de detailpagina van een deployment en, als de configuratie sinds deze is gebouwd is gewijzigd, krijgt u een melding Environment variables updated since this deployment die u vertelt dat de wijziging niet van kracht wordt totdat u redeploy.

Geheimen

Vink Mark as secret aan voor alles wat u niet in een chat zou plakken: API-sleutels, databasewachtwoorden, tokens, handtekeningssleutels.

Geheime waarden zijn gemaskeerd in het paneel en dragen een secret badge. Niet-geheime waarden tonen een marker (plain).

Een geheime waarde kan na het opslaan niet terug worden gelezen, niet door u en niet door iemand anders in het paneel. U kunt deze vervangen (klik op het bewerkingspictogram, typ een nieuwe waarde, opslaan), maar u kunt deze niet onthullen. Houd uw eigen kopie in een wachtwoordmanager voordat u deze hier opslaat.

Orbit volgt ook hoe lang een waarde op zijn plaats is en toont een leeftijdsbadge op oudere variabelen, met een hint die rotatie aanbeveelt. Dat is een duwtje, geen handhaving.

Bewerken en Verwijderen

Klik op het bewerkingspictogram naast een variabele om de waarde ervan te wijzigen. Klik op Delete om deze te verwijderen en bevestig: het dialoogvenster waarschuwt dat builds die ervan afhangen, zullen onderbreken, wat de nauwkeurige beschrijving is van wat gebeurt bij de volgende implementatie.

Bulkimport en Export

Twee knoppen bovenaan het tabblad verwerken bulk werk.

Import .env opent een plakdoos. Plak de inhoud van een .env bestand, kies een bereik, en Orbit vertelt u hoeveel variabelen het heeft gedetecteerd en hoeveel het als geheim zal markeren. Het markeert sleutels automatisch op basis van hun namen, dus alles wat SECRET, TOKEN, KEY, PASSWORD en dergelijke bevat, wordt vóór import als geheim gemarkeerd. Er is een optie Overwrite existing variables with the same key, standaard uit.

Download .env produceert een sjabloon met de variabele names only, zonder waarden. Het is bedoeld om te delen met een teamgenoot die hun eigen waarden invult, niet als back-up te gebruiken.

Het downloaden van een .env sjabloon omvat nooit waarden, ook niet voor niet-geheime variabelen. Er is geen manier om waarden uit Orbit te exporteren. Als u een kopie van een waarde nodig hebt, haalt u deze op van waar u deze oorspronkelijk hebt gegenereerd.

Variabelen Tussen Omgevingen Kopiëren

Het paneel Copy variables between environments kopieert een hele set van het ene bereik naar het ander. Kies een From (projectniveau of een specifieke omgeving) en een To, vink optioneel Overwrite variables that already exist in the target aan, en klik op Preview om precies te zien hoeveel worden toegevoegd, bijgewerkt en overgeslagen voordat u zich vastlegt.

Er is ook een Env sync check pagina die productie en staging sleutel voor sleutel vergelijkt en rapporteert wat alleen in de ene voorkomt, wat verschilt en wat overeenkomt. Het is het juiste hulpmiddel voor "waarom werkt staging en productie niet".

Variabelen Tussen Projecten Delen

Als meerdere projecten dezelfde referentie nodig hebben, gebruik dan een env group in plaats van deze in elk project te kopiëren. Ga naar Orbit, vervolgens Env groups, maak een groep aan, voeg variabelen toe en link de projecten die ze nodig hebben.

Groepsvariabelen worden op buildtijd ingespoten, en variabelen op projectniveau en omgevingsniveau hebben voorrang op groepsvariabelen. U kunt maximaal 20 groepen per account hebben.

Framework-opmerkingen

Welke variabelen in de browser terechtkomen, wordt bepaald door uw framework, niet door Orbit. Orbit spuit alles in bereik in; het framework bepaalt wat wordt blootgesteld.

Next.js: sleutels met voorvoegsel NEXT_PUBLIC_ worden op buildtijd in de browsermap ingevoegd. Alles ander blijft aan de serverzijde.
Vite: sleutels met voorvoegsel VITE_ worden blootgesteld aan de browser. Alles ander is alleen op buildtijd.
Node.js apps: alles in bereik staat op process.env tijdens de build, en tijdens runtime wanneer Server mode aan staat.

Markeer nooit een waarde als geheim en geef deze dan ook voorvoegsel NEXT_PUBLIC_ of VITE_. De geheime vlag bepaalt alleen of het paneel u de waarde toont; het voorvoegsel bepaalt of uw framework het naar de browser van elke bezoeker stuurt. Het voorvoegsel wint.

Controleren Wat Een Build Werkelijk Heeft Ontvangen

Elke implementatiedetailpagina geeft een lijst van de omgevingsvariabele keys die op buildtijd zijn ingespoten en vergelijkt deze met uw huidige configuratie: toegevoegd, gewijzigd, verwijderd en ongewijzigd. Teal-sleutels kwamen van een omgevingsspecifieke override, grijze van projectniveau. Waarden worden nooit opgeslagen of weergegeven, maar als u een sleutel aanwijst, krijgt u een SHA-256-vingerafdruk, wat voldoende is om te bevestigen dat twee omgevingen dezelfde waarde bevatten zonder deze te onthullen.

Dit is het definitieve antwoord op "bereikt mijn variabele werkelijk de build". Controleer dit voordat u iets anders wijzigt.

Probleemoplossing

De variabele is tijdens runtime ongedefinieerd. Controleer of de implementatie na de wijziging plaatsvond, controleer vervolgens of het bereik deze omgeving dekt, controleer vervolgens de framework-voorvoegselregels hierboven. In die volgorde.

Het werkt in productie maar niet in een preview. De variabele is alleen op productie gericht, of een projectbrede variabele heeft preview uitgeschakeld onder Available in. Dat is meestal opzettelijk.

Het werkt lokaal maar niet in de build. Uw lokale .env bestand is niet in de repository, en mag daar ook niet in zitten. Importeer het met Import .env en kies het juiste bereik.

Staging mist alles wat productie heeft. Schakel Inherit production env vars in onder Settings, onder Staging: environment variables, of gebruik Copy variables between environments.