Umgebungsvariablen pro Umgebung festlegen

Orbit lets you decide exactly which builds see which environment variables, so production credentials never end up in a publicly reachable branch preview. This guide covers how scope and precedence…

Warum Dies Wichtig Ist

Eine Branch-Preview erhält eine öffentliche URL. Jeder mit dem Link kann sie laden. Wenn eine Variable für jede Umgebung gültig ist, wird sie in den Build dieser Preview eingefügt, und was die Preview damit tut, tut sie mit deinen Production-Anmeldedaten.

Das ist der ganze Grund, warum diese Seite existiert. Alles Folgende dient einer Regel: Production-Secrets gehören in Production-Scope und nirgends sonst.

Wie Scoping Funktioniert

Jede Variable hat einen Scope, der entscheidet, wann sie während des Builds eingefügt wird.

Scope	Eingefügt in
Alle Umgebungen (projektübergreifend)	Jeden Build dieses Projekts, es sei denn, du beschränkst ihn
Ein spezifischer Umgebungs-Override	Builds nur dieser einen Umgebung

Wenn derselbe Schlüssel auf beiden Ebenen vorhanden ist, gewinnt der spezifischere. Ein Umgebungs-Level-Override schlägt eine projektübergreifende Variable mit demselben Schlüssel. Die Seite "Env vars" erklärt dies im Untertitel des Abschnitts "All environments": projektübergreifende Variablen sind in jedem Build verfügbar, und Umgebungs-Level-Overrides haben Vorrang.

Projektübergreifende Variablen können auch eingegrenzt werden, ohne zu einem Override zu werden. Das Steuerelement Available in bietet drei Umgebungstypen (production, staging, preview) und du kannst jeden von ihnen abwählen.

Eine Variable Mit Einem Scope Hinzufügen

Öffne dein Projekt in Orbit und klicke auf die Registerkarte Env vars.
Scrolle zum Formular Add variable am unteren Ende.
Fülle KEY und value aus.
Nutze das Dropdown-Menü Scope:
- All environments (project-wide) fügt es in jeden Build ein.
- [Environment name] only ([type] override) beschränkt es auf diese eine Umgebung.
Wenn du "project-wide" gewählt hast, nutze die Schaltflächen Available in, um Umgebungstypen abzuwählen, die diese Variable nicht erreichen soll.
Aktiviere Mark as secret für alles Vertrauliche.
Klicke auf Add.

Vor dem Commit zeigt dir das Formular, was es tun wird. Ein Override zeigt eine Benachrichtigung, die besagt, dass es nur auf die Builds dieser Umgebung angewendet wird und dass projektübergreifende Variablen anderswo noch gelten. Eine eingeschränkte projektübergreifende Variable zeigt genau, in welche Umgebungstypen sie eingefügt wird.

Eine Production-Only Variable Hinzufügen

Zwei gleichwertige Wege:

Wähle im Dropdown Scope deine Production-Umgebung (sie trägt ein grünes production Badge), oder
Behalte den Scope als All environments und wähle staging und preview unter Available in ab.

In jedem Fall ist die Variable abwesend, wenn ein Preview- oder Staging-Build ausgeführt wird.

"Abwesend" bedeutet abwesend, nicht leer. Code, der process.env.STRIPE_SECRET_KEY in einem Preview-Build liest, erhält undefined, und je nach Schreibweise kann dies beim Build fehlschlagen oder, noch schlimmer, stillschweigend einen falschen Branch nehmen. Gib Previews einen Test-Modus-Wert statt keinen Wert.

Das Sichere Muster

Das Muster, das dieses Problem für die meisten Projekte sauber löst:

Füge die Production-Anmeldedaten, scoped nur auf die Production-Umgebung, hinzu.
Füge eine Variable mit dem gleichen Schlüssel hinzu, die einen Test- oder Sandbox-Wert enthält, im projektübergreifenden Scope.

Production-Builds erhalten den Production-scoped-Wert, weil der spezifischere Scope gewinnt. Previews und Staging erhalten den Test-Wert. Nichts ist nirgends undefined, und kein Production-Secret erreicht jemals eine Preview.

Wende dies auf an:

Production-Datenbank-URLs
Secret Keys des Payment-Providers, mit den Test-Keys des Providers für Previews
Email-Sending-Keys, damit eine Preview keine echten Kunden anmailen kann
Admin-Tokens und Signing-Secrets
Alles mit Pro-Call-Kosten

Production-Variablen in Staging Erben

Wenn deine Staging-Umgebung der Production nahe ist und du nur ein paar Werte überschreiben möchtest, musst du nicht alles duplizieren.

Gehe zu Settings, finde Staging: environment variables und aktiviere Inherit production env vars. Production-Variablen werden dann in Staging-Builds mit niedrigerer Priorität als Staging-spezifische Overrides zusammengeführt, sodass alles, das du explizit auf Staging setzt, immer noch gewinnt.

Vererbung kopiert Production-Werte in Staging-Builds, einschließlich Production-Anmeldedaten. Aktiviere dies nur, wenn deine Staging-Umgebung geschützt ist. Staging unterstützt sowohl ein Passwort als auch eine IP-Allowlist in den Abschnitten Staging: access protection und Staging: IP allowlist von Settings. Das Aktivieren der Vererbung für eine ungeschützte Staging-Umgebung reproduziert genau die Exposure, um die es auf dieser Seite geht.

Vorhandene Variablen Anzeigen und Bearbeiten

Die Registerkarte "Env vars" gruppiert Variablen in:

All environments oben, mit projektübergreifenden Variablen
Ein ausklappbarer Abschnitt pro Umgebung, mit Overrides dieser Umgebung und einer Anzahl

Darüber gibt es ein Suchfeld und einen Filter Secrets only.

Die Badges neben jedem Variablennamen zeigen, welche Umgebungstypen es erreicht. Eine Variable mit production und preview aber nicht staging fehlt in Staging-Builds, und diese Badge-Reihe ist die schnellste Möglichkeit, eine lange Liste zu überprüfen.

Klicke auf das Bearbeitungssymbol, um einen Wert zu ändern. Der aktuelle Wert einer Secret-Variable kann nicht offenbart, nur ersetzt werden.

Zwischen Umgebungen Kopieren und Vergleichen

Copy variables between environments kopiert einen ganzen Satz von einem Scope zu einem anderen. Wähle einen From und ein To, aktiviere optional Overwrite variables that already exist in the target und klicke auf Preview, um zu sehen, wie viele hinzugefügt, aktualisiert und übersprungen werden, bevor du bestätigst.

Die Seite Env sync check vergleicht Production und Staging Schlüssel für Schlüssel und zeigt, was nur in einem existiert, welche unterschiedliche Werte haben und welche übereinstimmen. Dies ist der richtige erste Anlaufpunkt für "Staging funktioniert und Production nicht" oder umgekehrt.

Unterschiedliche Werte zwischen Production und Staging ist für die meisten Secrets normal und erwartet. Die Sync-Seite sagt das auch. Worauf du achten möchtest, ist ein Schlüssel, der in einer Umgebung vorhanden ist und in der anderen fehlt.

Variablen Über Projekte Hinweg Teilen

Wenn mehrere Projekte die gleiche Anmeldedaten benötigen, nutze eine env group statt sie in jedes Projekt zu kopieren. Gehe zu Orbit, dann Env groups, erstelle eine Gruppe, füge die Variablen hinzu und verlinke die Projekte, die sie benötigen.

Gruppenvariablen werden während des Builds eingefügt und sitzen am unteren Ende der Precedence-Ordnung: Projekt-Level- und Umgebungs-Level-Variablen haben beide Vorrang vor Gruppenvariablen. Du kannst bis zu 20 Gruppen auf einem Account haben.

Das Löschen einer Gruppe entfernt diese Variablen aus zukünftigen Builds aller verknüpften Projekte. Bereits abgeschlossene Builds sind nicht betroffen.

Massenimport

Die Schaltfläche Import .env öffnet ein Einfügungsfeld. Füge eine .env Datei ein, wähle einen Scope und Orbit zeigt, wie viele Variablen es gefunden hat und wie viele es als Secret markiert. Schlüssel mit SECRET, TOKEN, KEY, PASSWORD und ähnlichen Begriffen werden automatisch gekennzeichnet. Es gibt eine Option Overwrite existing variables with the same key, die standardmäßig ausgeschaltet ist.

Download .env erstellt eine Vorlage mit Variablennamen nur, ohne Werte, zum Teilen mit einem Teamkollegen, der seine eigenen liefert.

Wähle den Scope im Import-Dialog, bevor du auf Import klickst, nicht danach. Das Importieren einer ganzen Production .env mit projektübergreifendem Scope schiebt jeden Production-Secret in deine Preview-Builds auf einmal, und die Behebung besteht darin, sie zu löschen und erneut hinzuzufügen, nicht eine Einstellung zu ändern.

Überprüfen, Was Ein Build Tatsächlich Erhalten Hat

Jede Deployment-Detailseite listet die Umgebungsvariablen-Schlüssel auf, die beim Build eingefügt wurden, und vergleicht sie mit deiner aktuellen Konfiguration: hinzugefügt, geändert, entfernt, unverändert. Türkise Schlüssel stammen von einem Umgebungs-spezifischen Override, graue von Projekt-Level.

Werte werden nie gespeichert oder angezeigt. Das Hovern über einen Schlüssel gibt einen SHA-256-Fingerprint, der ausreicht, um zu bestätigen, dass zwei Umgebungen den gleichen Wert haben, ohne ihn offenzulegen.

Wenn sich die Konfiguration nach diesem Deployment geändert hat, sagt die Seite dies mit einer Benachrichtigung Environment variables updated since this deployment und erinnert dich, dass die Änderung erst wirksam wird, wenn du erneut deployst.

Variablenänderungen gelten niemals für das Deployment, das bereits live ist. Sie werden eingefügt, wenn ein Build ausgeführt wird. Nach dem Ändern von etwas, das deine App benötigt, deploye erneut.

Weiterführende Lektüre

Umgebungsvariablen für die Grundlagen, Secrets und Framework-Präfix-Regeln
Branch Preview Deployments in Orbit für die Funktionsweise öffentlicher Previews
Viewing Build Logs für den Build-Zeit-Variablen-Diff