Geheimnisverwaltung und Umgebungsvariablen

In einer React-Anwendung gibt es zwei Klassen von Umgebungsvariablen: serverseitige (niemals an den Browser gesendet) und clientseitige (in das JavaScript-Bundle eingebettet). Zu verstehen, welcher Klasse Ihre Variablen angehören, ist der erste Schritt bei der Geheimnisverwaltung, denn clientseitige Variablen sind nach der Bereitstellung des Bundles praktisch öffentlich.

In Vite-Projekten werden nur Variablen mit dem Präfix VITE_ in das Client-Bundle aufgenommen. VITE_PUBLIC_API_URL=https://api.example.com ist im Browser-Code über import.meta.env.VITE_PUBLIC_API_URL verfügbar. Alle anderen Variablen werden beim Build aus dem Bundle entfernt und bleiben ausschließlich serverseitig verfügbar.

In Next.js macht das Präfix NEXT_PUBLIC_ eine Variable für Browser-JavaScript verfügbar. NEXT_PUBLIC_ANALYTICS_ID=UA-123 wird in das Client-Bundle eingebettet. Variablen ohne dieses Präfix (wie DATABASE_URL) sind nur in serverseitigem Code (Server Components, API-Routen und Server Actions) verfügbar und werden nie an den Browser gesendet.

Eine Variable ohne Präfix ist dennoch zugänglich, wenn sie versehentlich serialisiert wird. Wenn beispielsweise eine Server Component ihr vollständiges Konfigurationsobjekt als Prop an eine Client Component übergibt und diese Konfiguration DATABASE_URL enthält, erscheint dieses Geheimnis im an den Browser gesendeten HTML. Sorgfältiges Prop-Drilling und eine Prüfung der Serialisierung verhindern dies.

Folgendes darf niemals im Client-Bundle enthalten sein: Datenbankverbindungszeichenfolgen und Passwörter, geheime API-Schlüssel von Drittanbietern (Stripe-Secret-Key, OpenAI-API-Key), private RSA/EC-Schlüssel, JWT-Signaturgeheimnisse und interne Authentifizierungstoken für Services. Wenn Sie etwas davon für einen API-Aufruf benötigen, leiten Sie diesen über einen Server-Endpunkt weiter.

Das Backend for Frontend (BFF)-Muster ordnet eine dünne Server-Schicht zwischen der React-App und sensiblen externen Diensten an. Der Client ruft /api/stripe/charge auf, der BFF-Server fügt den Stripe-Secret-Key hinzu und ruft die Stripe-API auf, und der BFF gibt nur die erforderlichen Antwortdaten zurück. Geheimnisse bleiben dauerhaft auf dem Server.

dotenv-vault verschlüsselt Ihre .env-Datei und ermöglicht die sichere Freigabe und Bereitstellung über Umgebungen hinweg, ohne Klartextgeheimnisse in die Versionsverwaltung einzuchecken. Zu den Alternativen für die Produktion gehören HashiCorp Vault (Enterprise), AWS Parameter Store (SSM) und GCP Secret Manager – sie alle bieten den API-basierten Abruf von Geheimnissen zur Laufzeit statt zur Build-Zeit.

CI/CD-Plattformen (GitHub Actions, GitLab CI) stellen verschlüsselte Geheimnisspeicher bereit, auf die während der Builds als Umgebungsvariablen zugegriffen werden kann. Speichern Sie Geheimnisse in GitHub Secrets und referenzieren Sie sie in Workflows als ${{ secrets.STRIPE_SECRET_KEY }}. Geheimnisse werden in Logs maskiert und niemals in das Build-Artefakt aufgenommen.

Next.js und Vite unterstützen mehrere .env-Dateien: .env (alle Umgebungen), .env.local (lokale Überschreibungen, von Git ignoriert), .env.development, .env.production. Die lokale Datei überschreibt Werte aus der gemeinsamen Datei und ermöglicht eine entwicklerspezifische Konfiguration, ohne andere Umgebungen zu beeinflussen.

Prüfen Sie nach dem Build das JavaScript-Bundle auf versehentlich offengelegte Geheimnisse. Führen Sie grep -r "password|secret|api_key" dist/ aus oder verwenden Sie ein spezielles Tool wie eine strings-Analyse der erstellten Dateien. Einige Geheimnisse lassen sich, wenn sie versehentlich enthalten sind, anhand ihres Formats eindeutig erkennen (UUIDs, Base64-Zeichenfolgen oder Schlüsselpräfixe wie sk_live_).

Jede Umgebung und jeder Dienst sollte nur auf die Geheimnisse zugreifen können, die er benötigt. Der React-Client benötigt überhaupt keine Geheimnisse – er sollte nur öffentliche Identifikatoren erhalten. Der BFF-Server benötigt nur die Geheimnisse, die für die von ihm aufgerufenen APIs erforderlich sind. Entwicklungsumgebungen sollten nicht für die Produktion bestimmte API-Schlüssel mit eingeschränkten Berechtigungen und Ausgabenlimits verwenden.

Vite verwendet VITE_ und Next.js verwendet NEXT_PUBLIC_, um Variablen im Browser-Bundle verfügbar zu machen. Alle anderen Variablen sind nur serverseitig verfügbar. Nehmen Sie Datenbankpasswörter, geheime API-Schlüssel oder JWT-Signaturgeheimnisse niemals in Client-Code auf. Verwenden Sie das BFF-Muster, um sensible API-Aufrufe weiterzuleiten. Verwenden Sie dotenv-vault, AWS Parameter Store oder GitHub Secrets für die Geheimnisverwaltung in der Produktion. Prüfen Sie erstellte Bundles auf versehentlich offengelegte Geheimnisse.