# Vercel: Umgebungsvariablen ohne .env in Git
> Umgebungsvariablen, Entwicklung/Vorschau/Produktion, ein neues Deployment und die sichere Prüfung von Schlüsseln in Next.js, ohne Geheimnisse an den Browser weiterzugeben.
Source: https://ailoot.ai/blog/de/vercel-environment-variables/
Canonical: https://ailoot.ai/blog/de/vercel-environment-variables/
Language: de
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-229
Revision: sha256-b548a4dc5316fc0fd5121681074f0cd77ab4de46ab7229d7d0396011a062cdf3
Das Wichtigste
Wenn die `.env`-Datei mit Ihren Geheimnissen nicht in Git ist, fügen Sie die erforderlichen Variablen im Abschnitt **Environment Variables** Ihres Vercel-Projekts hinzu. Wählen Sie die Umgebung aus, speichern Sie die Einstellungen und erstellen Sie ein neues Deployment: Bereits bereitgestellte Versionen ändern sich nicht. Fügen Sie in Next.js einem geheimen Schlüssel nicht das Präfix `NEXT_PUBLIC_` hinzu: Sein Wert wird während des Builds in den Browser-Code aufgenommen.
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](https://ailoot.ai/docs/).
## 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](https://ailoot.ai/blog/de/vibe-coding-security/). 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.
| Was zu prüfen ist | Mögliche Optionen | Warum es wichtig ist |
|----|----|----|
| Vercel-Umgebung | Development, Preview, Production | Die Einstellung muss für die Version gelten, die Sie prüfen |
| Ort des Auslesens | Server oder Browser | Ein privater Schlüssel darf nicht in clientseitigen Code aufgenommen werden |
| Zeitpunkt des Auslesens | Build-Zeit oder Ausführung der Serverfunktion | In Next.js werden öffentliche Werte während des Builds festgelegt |
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](https://ailoot.ai/blog/de/astro-vs-nextjs-for-ai-built-sites/) 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.
| Symptom | Was zu prüfen ist |
|----|----|
| Funktioniert lokal, aber nicht in Preview | Ob der Name in den Preview-Einstellungen des Projekts vorhanden ist; ob ein anderer Branch ausgewählt ist |
| Preview funktioniert, Production aber nicht | Ob der Name für Production festgelegt ist; ob nach dem Speichern eine neue Hauptversion erstellt wurde |
| Ein Preview-Branch verhält sich anders | Ob für diesen Branch ein Wert mit demselben Namen festgelegt ist, der die allgemeine Einstellung überschreibt |
| Der Server sieht die Variable, der Browser aber nicht | In Next.js ist dies bei einer nicht öffentlichen Variable zu erwarten; verschieben Sie keinen privaten Schlüssel in den Browser |
| Die öffentliche Next.js-Bezeichnung hat weiterhin ihren alten Wert | Ob ein neuer Build mit dem erforderlichen Wert erstellt wurde; ob die geöffnete URL zu diesem Deployment gehört |
| Der öffentliche Name stimmt, aber die Ersetzung funktioniert nicht | Ob der Code die Variable dynamisch mit `process.env[varName]` ausliest: Next.js bettet solche Referenzen nicht ein |
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](https://ailoot.ai/blog/de/coolify-claude-code-deploy/). Die Schaltflächennamen und Konfigurationsschritte von Vercel gelten dort nicht.
### Quellen
- [Vercel-Umgebungsvariablen](https://vercel.com/docs/environment-variables)
- [Vercel-Umgebungsvariablen hinzufügen und verwalten](https://vercel.com/docs/environment-variables/managing-environment-variables)
- [Next.js-Umgebungsvariablen](https://nextjs.org/docs/app/guides/environment-variables)
[Zu Ailoot](https://ailoot.ai/).
## Fragen und Antworten
### Warum ist die Variable nach dem Speichern in Vercel weiter undefined?
Prüfe Projekt, Umgebung und gegebenenfalls branchbezogenen Geltungsbereich. Erstelle danach eine neue Bereitstellung. Vorhandene Bereitstellungen erhalten die Variable nicht allein durch das Speichern einer neuen Einstellung.
### Kann ich NEXT_PUBLIC_ ergänzen, damit meine Next.js-App ein Geheimnis sieht?
Verwende diesen Präfix nicht für Geheimnisse: Er übernimmt den Wert beim Build in den Browsercode. Halte den Wert auf dem Server und prüfe seine Existenz, ohne den Schlüssel auszugeben.
## Ailoot · Das Unternehmen und sein Projektportfolio
Ailoot baut auf bewährte Betriebserfahrung, einen großen Kundenstamm, stabilen Service und kontinuierliche KPI-Kontrolle.
Das Unternehmen und sein Projektportfolio: Millionen von Kunden; monatliche Umsätze in Milliardenhöhe.
Ailoot nutzt diese Betriebserfahrung für den API-Zugang zu KI-Funktionen in Kundenprodukten, Agenten, Anwendungen und Automatisierungen.