Umgebungsvariablen

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…

Umgebungsvariablen speichern die Konfiguration und Geheimnisse, die Ihre App bei der Erstellung und zur Laufzeit benötigt, z. B. API-Schlüssel, Datenbank-URLs und Feature-Flags, ohne dass sie im Repository gespeichert sind. Dieser Leitfaden behandelt, wo sie in Orbit gespeichert sind, wie Umfang und Priorität funktionieren, das Markieren eines Werts als Geheimnis, Massenimport und -export sowie die Fehler, die dazu führen, dass eine Variable irgendwie immer undefiniert ist.

Wo sie gespeichert sind

Öffnen Sie Ihr Projekt in Orbit und klicken Sie auf die Registerkarte Env vars unter /orbit/<project-id>/env-vars.

Die Seite ist in Abschnitte organisiert:

Alle Umgebungen oben: projektweite Variablen, die bei jedem Build verfügbar sind.
Ein ausklappbarer Abschnitt pro Umgebung (Produktion, Staging und alle Vorschau-Umgebungen), der die Überridies dieser Umgebung enthält.

Über der Liste befindet sich ein Suchfeld und ein Filter Nur Geheimnisse, die die schnelle Navigation durch eine lange Liste ermöglichen.

Wie der Umfang funktioniert

Umfang	Was es betrifft
Alle Umgebungen (projektweit)	Wird bei jedem Build dieses Projekts eingefügt
Umgebungsspezifisches Override	Gilt nur für diese eine Umgebung und hat Vorrang vor dem projektweiten Wert mit demselben Schlüssel

Der Untertitel auf der Seite erklärt die Regel deutlich: projektweite Variablen sind in jedem Build verfügbar, und umgebungsspezifische Überridies haben Vorrang.

Eine typische Einrichtung ist eine projektweite Variable DATABASE_URL, die auf eine Test-Datenbank verweist, mit einem Override auf Produktionsebene, das auf die echte verweist. Production-Builds erhalten die echte Datenbank, alles andere erhält die Test-Datenbank, und nichts, das Sie später hinzufügen, leitet versehentlich Produktionsanmeldeinformationen in eine Vorschau-Umgebung weiter.

Es gibt auch ein Steuerelement Verfügbar in für projektweite Variablen, mit dem Sie bestimmte Umgebungstypen ausschließen können (production, staging, preview) von einer Variablen, die ansonsten projektweit ist.

Ausführliche Informationen zur Bereichsfestlegung pro Umgebung, einschließlich der Sicherheitserwägungen, finden Sie unter Umgebungsvariablen pro Umgebung konfigurieren.

Eine projektweite Variable wird in Branch-Vorschau-Builds eingefügt, und Vorschau-URLs sind öffentlich für jeden, der den Link hat, erreichbar. Produktionsdatenbank-Anmeldeinformationen, Live-Zahlungsschlüssel und Admin-Token müssen nur für die Produktion gelten. Dies ist das Wichtigste, das man auf dieser Seite richtig machen muss.

Eine Variable hinzufügen

Scrollen Sie zum Formular Add variable (Variable hinzufügen) unten auf der Registerkarte Env vars.
Geben Sie den KEY ein, z. B. NEXT_PUBLIC_API_URL.
Geben Sie den Wert ein.
Wählen Sie einen Umfang: Alle Umgebungen (projektweit) oder ein spezifisches Umgebungs-Override.
Wenn Sie projektweit gewählt haben, verwenden Sie die Schaltflächen Verfügbar in, um alle Umgebungstypen abzuwählen, die diese Variable nicht erreichen sollte.
Aktivieren Sie Mark as secret (Als Geheimnis markieren) für alles Vertrauliche.
Klicken Sie auf Add (Hinzufügen).

Das Formular teilt Ihnen mit, was es tun wird, bevor Sie bestätigen: ein Umgebungs-Override zeigt einen Hinweis an, dass es nur auf die Builds dieser Umgebung angewendet wird, und eine eingeschränkte projektweite Variable zeigt, welche Umgebungstypen es eingefügt werden.

Wann Änderungen wirksam werden

Das Hinzufügen, Bearbeiten oder Löschen einer Variablen ändert die Bereitstellung, die derzeit aktiv ist, nicht. Variablen werden eingefügt, wenn ein Build ausgeführt wird, daher gilt die Änderung ab der nächsten Bereitstellung. Stellen Sie erneut bereit, nachdem Sie alles geändert haben, worauf Ihre App angewiesen ist.

Orbit ist hier eindeutig. Öffnen Sie die Detailseite einer Bereitstellung, und wenn sich die Konfiguration seit ihrer Erstellung geändert hat, erhalten Sie einen Hinweis Environment variables updated since this deployment (Umgebungsvariablen seit dieser Bereitstellung aktualisiert), der Sie darauf hinweist, dass die Änderung erst nach einer erneuten Bereitstellung wirksam wird.

Geheimnisse

Aktivieren Sie Mark as secret (Als Geheimnis markieren) für alles, das Sie nicht in einen Chat einfügen würden: API-Schlüssel, Datenbank-Passwörter, Token, Signaturschlüssel.

Geheime Werte werden im Bereich maskiert und tragen ein Badge secret (Geheimnis). Nicht-geheime Werte zeigen einen Marker (plain) (einfach).

Der Wert eines Geheimnisses kann nach dem Speichern nicht zurückgelesen werden, nicht von Ihnen und nicht von jemand anderem im Bereich. Sie können ihn ersetzen (klicken Sie auf das Bearbeitungssymbol, geben Sie einen neuen Wert ein, speichern), aber Sie können ihn nicht offenlegen. Behalten Sie Ihre eigene Kopie in einem Passwort-Manager, bevor Sie sie hier speichern.

Orbit verfolgt auch, wie lange ein Wert an Ort und Stelle ist, und zeigt ein Alter-Badge auf älteren Variablen mit einem Hinweis, der eine Rotation nahelegt. Das ist ein Ansporn, keine Erzwingung.

Bearbeiten und Löschen

Klicken Sie auf das Bearbeitungssymbol neben einer Variablen, um ihren Wert zu ändern. Klicken Sie auf Delete (Löschen), um sie zu entfernen, und bestätigen Sie: Der Dialog warnt, dass Builds, die davon abhängen, unterbrochen werden, was eine genaue Beschreibung dessen ist, was beim nächsten Deploy geschieht.

Massenimport und -export

Zwei Schaltflächen oben auf der Registerkarte verwalten Massenarbeit.

Import .env öffnet ein Einfügungsfeld. Fügen Sie den Inhalt einer Datei .env ein, wählen Sie einen Umfang, und Orbit teilt Ihnen mit, wie viele Variablen erkannt wurden und wie viele als Geheimnis markiert werden. Es kennzeichnet Schlüssel automatisch anhand ihrer Namen, daher wird alles, das SECRET, TOKEN, KEY, PASSWORD und ähnlich enthält, vor dem Import als Geheimnis markiert. Es gibt eine Option Overwrite existing variables with the same key (Existierende Variablen mit demselben Schlüssel überschreiben), die standardmäßig ausgeschaltet ist.

Download .env erstellt eine Vorlage mit den Variablennamen nur, ohne Werte. Sie ist dazu bestimmt, mit einem Teamkollegen geteilt zu werden, der dann seine eigenen Werte ausfüllt, nicht als Sicherung verwendet zu werden.

Das Herunterladen einer Vorlage .env enthält niemals Werte, auch nicht für nicht-geheime Variablen. Es gibt keine Möglichkeit, Werte aus Orbit zu exportieren. Wenn Sie eine Kopie eines Werts benötigen, holen Sie ihn sich von dort, wo Sie ihn ursprünglich generiert haben.

Kopieren von Variablen zwischen Umgebungen

Der Bereich Copy variables between environments (Variablen zwischen Umgebungen kopieren) kopiert einen ganzen Satz von einem Umfang zu einem anderen. Wählen Sie einen From (Von) (Projektebene oder eine bestimmte Umgebung) und einen To (Zu), aktivieren Sie optional Overwrite variables that already exist in the target (Variablen überschreiben, die bereits im Ziel vorhanden sind), und klicken Sie auf Preview (Vorschau), um genau zu sehen, wie viele hinzugefügt, aktualisiert und übersprungen werden, bevor Sie bestätigen.

Es gibt auch eine Seite Env sync check (Umgebungssynchronisierungsprüfung), die Produktion und Staging Schlüssel für Schlüssel vergleicht und meldet, was nur in einem vorhanden ist, sich unterscheidet und übereinstimmt. Dies ist das richtige Tool für "warum funktioniert Staging und Produktion nicht".

Freigabe von Variablen über Projekte hinweg

Wenn mehrere Projekte dieselbe Anmeldeinformation benötigen, verwenden Sie eine env group (Umgebungsgruppe), anstatt sie in jedes Projekt zu kopieren. Gehen Sie zu Orbit, dann Env groups, erstellen Sie eine Gruppe, fügen Sie Variablen hinzu, und verknüpfen Sie die Projekte, die sie benötigen.

Gruppenvariablen werden zur Build-Zeit eingefügt, und Variablen auf Projekt- und Umgebungsebene haben Vorrang vor Gruppenvariablen. Sie können bis zu 20 Gruppen auf einem Konto haben.

Framework-Notizen

Welche Variablen den Browser erreichen, wird von Ihrem Framework entschieden, nicht von Orbit. Orbit fügt alles im Umfang ein; das Framework entscheidet, was zu exponieren ist.

Next.js: Schlüssel mit Präfix NEXT_PUBLIC_ werden zur Build-Zeit in das Browser-Bundle eingebunden. Alles andere bleibt serverseitig.
Vite: Schlüssel mit Präfix VITE_ werden dem Browser ausgesetzt. Alles andere ist nur zur Build-Zeit.
Node.js-Apps: alles im Umfang befindet sich auf process.env während des Build, und zur Laufzeit, wenn Server mode (Servermodus) aktiviert ist.

Markieren Sie einen Wert niemals als Geheimnis und geben Sie ihm dann auch den Präfix NEXT_PUBLIC_ oder VITE_. Das Flag "Geheimnis" steuert nur, ob der Bereich Ihnen den Wert zeigt; der Präfix steuert, ob Ihr Framework ihn an den Browser jedes Besuchers sendet. Der Präfix gewinnt.

Überprüfung der tatsächlich von einem Build erhaltenen Inhalte

Jede Seite mit Bereitstellungsdetails listet die Schlüssel der Umgebungsvariablen keys auf, die zur Build-Zeit eingefügt wurden, und vergleicht sie mit Ihrer aktuellen Konfiguration: hinzugefügt, geändert, entfernt und unverändert. Dunkelgrüne Schlüssel stammen aus einem umgebungsspezifischen Override, graue aus Projektebene. Werte werden niemals gespeichert oder angezeigt, aber das Hovern über einen Schlüssel gibt einen SHA-256-Fingerabdruck, der ausreicht, um zu bestätigen, dass zwei Umgebungen denselben Wert enthalten, ohne ihn offenzulegen.

Dies ist die endgültige Antwort auf "erreicht meine Variable tatsächlich den Build". Überprüfen Sie dies, bevor Sie etwas anderes ändern.

Fehlerbehebung

Die Variable ist zur Laufzeit undefiniert. Überprüfen Sie, dass die Bereitstellung nach der Änderung erfolgt, überprüfen Sie dann, dass der Umfang diese Umgebung abdeckt, überprüfen Sie dann die Framework-Präfixregeln oben. In dieser Reihenfolge.

Es funktioniert in der Produktion, aber nicht in einer Vorschau. Die Variable ist nur auf die Produktion bezogen, oder eine projektweite Variable hat preview unter Available in (Verfügbar in) abgewählt. Das ist normalerweise beabsichtigt.

Es funktioniert lokal, aber nicht im Build. Ihre lokale Datei .env befindet sich nicht im Repository, und sollte auch nicht. Importieren Sie sie mit Import .env und wählen Sie den richtigen Umfang.

Staging fehlt alles, was die Produktion hat. Schalten Sie Inherit production env vars (Produktionsumgebungsvariablen erben) in Settings (Einstellungen) unter Staging: environment variables (Umgebungsvariablen) ein, oder verwenden Sie Copy variables between environments (Variablen zwischen Umgebungen kopieren).