Vercel: Umgebungsvariablen ohne .env in Git

Diese Anleitung richtet sich an ein Projekt, das bereits auf Vercel gehostet wird. Sie benötigen Zugriff auf dessen Einstellungen und müssen wissen, welche Variablen die Anwendung ausliest. Das folgende Beispiel gilt für Next.js; Variablennamen eines anderen Frameworks lassen sich nicht automatisch übernehmen. Die Anleitung basiert auf der offiziellen Dokumentation und wurde nicht mit einem echten Konto getestet.

Praktische Informationen zur Nutzung von Ailoot finden Sie in der Dokumentation.

Warum muss die .env-Datei bei Vercel nicht in Git gespeichert werden?#

Eine Umgebungsvariable ist eine Einstellung mit einem Namen und einem Wert, die eine Anwendung getrennt von ihrem Quellcode erhält. Mit dem Namen SERVICE_API_KEY kann das Programm beispielsweise auf den Schlüsselwert eines externen Dienstes zugreifen. Schreiben Sie den Schlüssel selbst nicht in die Anleitung, in Ihr Gespräch mit einem Agenten oder ins Repository.

Next.js kann Variablen aus lokalen .env*-Dateien laden. Eine lokale Datei und die Einstellungen eines Projekts in Vercel sind jedoch zwei getrennte Speicherorte. Wenn die Datei nicht ins Repository übertragen wird, legen Sie die Werte separat auf der Hosting-Plattform fest. Die Standardvorlage create-next-app nimmt .env-Dateien in .gitignore auf; die Next.js-Dokumentation warnt davor, sie fast immer ins Repository zu übertragen.

Wenn Sie noch unsicher sind, was in Quelldateien gespeichert werden darf, beginnen Sie mit der Sicherheitsprüfung für ein mit KI erstelltes Projekt. Hier geht es um eine engere Frage: Wo legen Sie die Konfiguration für ein bestimmtes Vercel-Deployment fest?

Ermitteln Sie zuerst, wo die Anwendung die Variable ausliest#

Erstellen Sie vor der Eingabe von Werten eine Liste der Namen, ohne die Geheimnisse selbst. Für jeden Namen müssen Sie drei Dinge ermitteln: welche Umgebung ihn verwendet, wo der Code läuft, der die Variable ausliest, und wann der Wert benötigt wird.

Die Umgebung Development ist für die lokale Entwicklung vorgesehen. Preview ist für Vorschau-Deployments und Production für die veröffentlichte Hauptversion. Für Preview können Einstellungen für einen bestimmten Git-Branch gelten: Diese überschreiben die allgemeinen Preview-Einstellungen mit denselben Namen.

In einem Next.js-Projekt sind Variablen ohne NEXT_PUBLIC_ standardmäßig auf dem Server verfügbar. Mit dem Präfix NEXT_PUBLIC_ kann der Wert in das an den Browser ausgelieferte JavaScript eingebettet werden. Das eignet sich für eine ausdrücklich öffentliche Einstellung, etwa eine nicht geheime Versionsbezeichnung, aber nicht für einen privaten API-Schlüssel. Auch ohne dieses Präfix darf der Anwendungscode ein Geheimnis nicht manuell an den Client zurückgeben.

Wenn Sie das Framework noch nicht ermittelt haben, bitten Sie den Agenten, es anhand der Projektdateien zu bestimmen. Der Vergleich von Astro und Next.js kann Ihnen helfen, die Unterschiede zu verstehen; die Regel für NEXT_PUBLIC_ lässt sich nicht auf jede React-Anwendung anwenden.

Die Hosting-Konfiguration gehört zu den Aufgaben bei der Arbeit an einer Anwendung mit einem KI-Agenten.

So fügen Sie einem Vercel-Projekt eine Variable hinzu#

Führen Sie die Schritte selbst im offiziellen Dashboard aus. Geben Sie dem Agenten keinen echten Schlüssel, damit er das Formular ausfüllt, und hängen Sie keinen Screenshot an, auf dem sein Wert zu sehen ist.

1. Öffnen Sie das Vercel-Dashboard und wählen Sie das richtige Projekt aus. Verlassen Sie sich nicht allein auf einen übereinstimmenden Repository-Namen: Prüfen Sie, ob Sie die Anwendung konfigurieren, die Sie öffnen möchten.
2. Öffnen Sie in der Seitenleiste der Projekteinstellungen Environment Variables.
3. Geben Sie unter Name den Namen ein, den die Anwendung ausliest, etwa SERVICE_API_KEY. Dies ist ein Beispielname. Erwartet der Code einen anderen Namen, verwenden Sie dessen exakte Schreibweise.
4. Geben Sie unter Value den Wert aus Ihrem Zugangsdaten-Speicher ein. Schreiben Sie ihn nicht in den Quellcode, einen Chat oder ein Prüfprotokoll.
5. Wählen Sie die Umgebung aus, für die diese Einstellung gelten soll. Verwenden Sie Preview, um eine Vorschauversion zu prüfen, und Production für die Hauptversion. Weisen Sie ein Geheimnis nicht automatisch allen Umgebungen zu.
6. Wenn die Preview-Einstellung für einen bestimmten Branch gilt, prüfen Sie den ausgewählten Branch und jede Überschreibung mit demselben Namen.
7. Klicken Sie auf Save.

Vercel stellt Projektvariablen sowohl während des Builds als auch bei der Ausführung serverseitiger Vercel Functions bereit. Dass ein Wert in Vercel verfügbar ist, bedeutet jedoch nicht, dass er an den Browser gesendet werden kann: Das hängt vom Anwendungscode und den Regeln des Frameworks ab.

Warum Sie nach dem Speichern ein neues Deployment benötigen#

Das Speichern einer Variable ändert bestehende Deployments nicht. Laut Vercel-Dokumentation müssen Sie das Projekt erneut deployen, damit die neue Einstellung die von Ihnen verwendete Version erreicht.

Bei der Arbeit mit Git können Sie ein neues Production-Deployment erstellen, indem Sie einen Commit in den unter Production Branch angegebenen Branch übertragen, und ein Preview-Deployment, indem Sie in einen anderen Branch übertragen. Nehmen Sie nicht an, dass der Hauptbranch immer main heißt: Prüfen Sie die Einstellung Ihres Projekts. Dies sollte eine reguläre, abgestimmte Projektveröffentlichung sein, ohne eine Datei mit Geheimnissen zum Commit hinzuzufügen.

Warten Sie nach dem Start des Deployments, bis der Build abgeschlossen ist, und öffnen Sie die URL des neuen Deployments. Notieren Sie dessen URL, Umgebung und Branch. Wenn Sie die alte URL eines einzelnen Deployments prüfen, werden die neuen Einstellungen dort nicht angezeigt.

In Next.js gilt eine weitere Bedingung: Referenzen wie process.env.NEXT_PUBLIC_RELEASE_LABEL werden während next build durch ihre Werte ersetzt. Der Wert steht nach dem Build fest. Wird die Einstellung ohne einen neuen Build geändert, wird bereits ausgeliefertes clientseitiges JavaScript nicht neu geschrieben.

So prüfen Sie das Ergebnis, ohne den Schlüssel offenzulegen#

Beginnen Sie mit einem sicheren Beispiel: einer ausdrücklich nicht geheimen Bezeichnung namens NEXT_PUBLIC_RELEASE_LABEL mit dem Wert preview-check. Das sind ein Beispielname und ein Beispieltext, kein Schlüssel und kein hier durchgeführter Test. Wenn eine Next.js-Anwendung diese Variable direkt über process.env.NEXT_PUBLIC_RELEASE_LABEL ausliest, kann sie die Bezeichnung nach einem neuen Build an der vorgesehenen Stelle in der Benutzeroberfläche anzeigen. Diese Prüfung bestätigt lediglich, dass die öffentliche Einstellung übergeben wurde.

Ein privater Schlüssel wird anders geprüft. Geben Sie weder seinen Wert noch einen Teil davon, seine Länge oder das gesamte process.env aus. Erstellen Sie keine öffentliche URL, die den Inhalt der Variablen zurückgibt. Prüfen Sie zunächst nur, ob die Einstellung auf dem Server „vorhanden / nicht vorhanden“ ist, und prüfen Sie anschließend separat die Anwendungsfunktion, die den Dienst nutzt. Eine vorhandene Einstellung beweist nicht, dass der Schlüssel gültig ist oder die erforderlichen Berechtigungen besitzt.

Sie können die Ergebnisse ohne Geheimnisse festhalten:

• Projekt, Umgebung und Branch stimmen mit den bei der Konfiguration ausgewählten Angaben überein;
• Sie prüfen die URL eines neuen Deployments, das nach dem Speichern der Variable erstellt wurde;
• der Build ist abgeschlossen, und die erforderliche Anwendungsfunktion wurde mit sicheren Testdaten ausgeführt;
• das Geheimnis wird weder im Browser noch in API-Antworten, Protokollen oder Gesprächen offengelegt.

Wenn die Funktion eine Zahlung ausführt, eine Nachricht sendet oder eine andere Aktion mit Folgen ausführt, verwenden Sie den dafür vorgesehenen Testmodus des Dienstes. Die Prüfung der Konfiguration allein berechtigt nicht zu einer echten Aktion.

Was Sie prüfen sollten, wenn der Wert weiterhin undefined ist#

undefined bedeutet, dass an dieser Stelle kein Wert abgerufen wurde. Prüfen Sie Name, Umgebung und Version der Reihe nach, ohne alle Einstellungen auf einmal zu ändern.

Auch wenn Sie Name, Umgebung und neue Version geprüft haben, beweist ein Fehler in der Funktion noch nicht, dass die Variable die Ursache ist. Untersuchen Sie den konkreten serverseitigen Codefehler, ohne Diagnosedaten mit Geheimnissen zu veröffentlichen. Diese Anleitung verspricht nicht, jede HTTP-500-Antwort zu beheben.

Der Wechsel zu Ihrem eigenen Server erfordert ein anderes Verfahren: Lesen Sie dazu die Anleitung zum Deployment eines Projekts mit Coolify. Die Schaltflächennamen und Konfigurationsschritte von Vercel gelten dort nicht.

Zu Ailoot.