Umgebungsvariablen verwenden

Astro bietet dir Zugang zu Vites eingebauter Unterstützung für Umgebungsvariablen und enthält einige Standard-Umgebungsvariablen für dein Projekt, mit denen du auf Konfigurationswerte für dein aktuelles Projekt zugreifen kannst (z.B. site, base), ob dein Projekt in Entwicklung oder Produktion läuft und mehr.

Astro bietet auch eine Möglichkeit, Ihre Umgebungsvariablen mit Typsicherheit zu verwenden und zu organisieren. Sie ist für die Verwendung innerhalb des Astro-Kontexts verfügbar (z. B. Astro-Komponenten, Routen und Endpunkte, UI-Framework-Komponenten, Middleware) und wird mit einem Schema in deiner Astro-Konfiguration (EN) verwaltet.

Vite’s integrierte Unterstützung

Astro nutzt die in Vite eingebaute Unterstützung für Umgebungsvariablen, die zum Zeitpunkt des Builds statisch ersetzt werden, und lässt dich mit einer seiner Methoden mit ihnen arbeiten.

Beachte, dass zwar alle Umgebungsvariablen im serverseitigen Code verfügbar sind, aber aus Sicherheitsgründen nur Umgebungsvariablen mit dem Präfix PUBLIC_ im clientseitigen Code verfügbar sind.

SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there

In diesem Beispiel ist PUBLIC_ANYBODY (zugänglich über import.meta.env.PUBLIC_ANYBODY) sowohl im Server- als auch im Client-Code verfügbar, während SECRET_PASSWORD (zugänglich über import.meta.env.SECRET_PASSWORD) nur serverseitig verfügbar ist.

IntelliSense für TypeScript

Standardmäßig bietet Astro eine Typdefinition für import.meta.env in astro/client.d.ts.

Du kannst zwar weitere benutzerdefinierte Umgebungsvariablen in .env.[mode]-Dateien definieren, aber du möchtest vielleicht TypeScript IntelliSense für benutzerdefinierte Umgebungsvariablen nutzen, denen das Präfix PUBLIC_ vorangestellt ist.

Um das zu erreichen, kannst du eine env.d.ts in src/ erstellen und ImportMetaEnv wie folgt konfigurieren:

interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // mehr Umgebungsvariablen...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Standard-Umgebungsvariablen

Astro enthält ein paar Umgebungsvariablen, die sofort einsatzbereit sind:

import.meta.env.MODE: Der Modus, in dem deine Website läuft. Das ist development, wenn du astro dev benutzt und production, wenn du astro build benutzt.
import.meta.env.PROD: true, wenn deine Website im Produktionsmodus läuft; andernfalls false.
import.meta.env.DEV: true, wenn deine Website im Entwicklungsmodus läuft; sonst false. Immer das Gegenteil von import.meta.env.PROD.
import.meta.env.BASE_URL: Die Basis-URL, von der aus deine Seite geladen wird. Sie wird durch die Konfigurationsoption base (EN) bestimmt.
import.meta.env.SITE: Diese wird auf die Option site (EN) gesetzt, die in der astro.config deines Projekts angegeben ist.

import.meta.env.ASSETS_PREFIX: Das Präfix für die von Astro erzeugten Asset-Links, wenn die Konfigurationsoption build.assetsPrefix (EN) gesetzt ist. Damit können Asset-Links erstellt werden, die nicht von Astro verarbeitet werden.

Verwende sie wie jede andere Umgebungsvariable.

const isProd = import.meta.env.PROD;
const isDev = import.meta.env.DEV;

Umgebungsvariablen definieren

`.env`-Dateien

Umgebungsvariablen können aus .env-Dateien in deinem Projektverzeichnis geladen werden.

Erstelle einfach eine .env Datei im Projektverzeichnis und füge ihr einige Variablen hinzu.

# Diese Funktion ist nur verfügbar, wenn sie auf dem Server ausgeführt wird!
DB_PASSWORD="foobar"
# Das wird überall verfügbar sein!
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"

Du kannst auch .production, .development oder einen benutzerdefinierten Modusnamen an den Dateinamen selbst anhängen (z.B. env.testing, .env.staging). So kannst du verschiedene Umgebungsvariablen zu verschiedenen Zeiten verwenden.

Die Befehle astro dev und astro build sind standardmäßig auf die Modi "development" bzw. "production" eingestellt. Du kannst diese Befehle mit dem --mode flag (EN) ausführen, um einen anderen Wert für mode zu übergeben und die passende .env Datei zu laden.

So kannst du den Entwicklungsserver betreiben oder deine Website mit verschiedenen APIs verbinden:

# Betreibe den Entwicklungsserver, der mit einer „Staging“-API verbunden ist
astro dev --mode staging

# Baue eine Website, die sich mit einer „Produktions“-API mit zusätzlichen Debug-Informationen verbindet
astro build --devOutput

# Erstelle eine Website, die sich mit einer „Test“-API verbindet
astro build --mode testing

Mehr über .env-Dateien findest du in der Vite-Dokumentation.

In der Astro-Konfigurationsdatei

Astro wertet die Konfigurationsdateien aus, bevor es deine anderen Dateien lädt. Das bedeutet, dass du mit import.meta.env in astro.config.mjs nicht auf Umgebungsvariablen zugreifen kannst, die in .env-Dateien gesetzt wurden.

Du kannst process.env in einer Konfigurationsdatei verwenden, um auf andere Umgebungsvariablen zuzugreifen, wie z.B. die von der CLI gesetzten.

Du kannst auch Vite’s loadEnv helper verwenden, um .env Dateien manuell zu laden.

import { loadEnv } from "vite";
const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

Mit pnpm kannst du keine Module importieren, die nicht direkt in deinem Projekt installiert sind. Wenn du pnpm verwendest, musst du vite installieren, um den loadEnv-Helper zu benutzen.

pnpm add vite --save-dev

Verwendung der Kommandozeilenschnittstelle (CLI)

Du kannst auch Umgebungsvariablen hinzufügen, während du dein Projekt ausführst:

POKEAPI=https://pokeapi.co/api/v2 npm run dev

POKEAPI=https://pokeapi.co/api/v2 pnpm run dev

POKEAPI=https://pokeapi.co/api/v2 yarn run dev

Abrufen von Umgebungsvariablen

Auf Umgebungsvariablen in Astro wird mit import.meta.env zugegriffen, wobei die in ES2020 hinzugefügte Funktion import.meta anstelle von process.env verwendet wird.

Verwende zum Beispiel import.meta.env.PUBLIC_POKEAPI, um die Umgebungsvariable PUBLIC_POKEAPI zu erhalten.

// Wenn import.meta.env.SSR === true
const data = await db(import.meta.env.DB_PASSWORD);

// Wenn import.meta.env.SSR === false
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);

Bei der Verwendung von SSR kann zur Laufzeit auf Umgebungsvariablen zugegriffen werden, je nachdem, welcher SSR-Adapter verwendet wird. Bei den meisten Adaptern kannst du mit process.env auf Umgebungsvariablen zugreifen, aber einige Adapter funktionieren anders. Für den Deno-Adapter verwendest du Deno.env.get(). Siehe Zugriff auf die Cloudflare-Laufzeit (EN) zur Handhabung von Umgebungsvariablen bei der Verwendung des Cloudflare-Adapters. Astro prüft zunächst die Serverumgebung auf Variablen, und wenn sie nicht vorhanden sind, sucht Astro in den .env-Dateien nach ihnen.

Typsichere Umgebungsvariablen

Mit der API astro:env kannst du ein typsicheres Schema für von dir gesetzte Umgebungsvariablen konfigurieren. So kannst du angeben, ob sie auf dem Server oder dem Client verfügbar sein sollen, und ihren Datentyp und zusätzliche Eigenschaften definieren.

Entwickelst du einen Adapter? Siehe, wie man einen Adapter mit astro:env kompatibel macht (EN).

Grundlegende Verwendung

Definiere dein Schema

Um ein Schema zu konfigurieren, füge die Option env.schema zu deiner Astro-Konfiguration hinzu:

import { defineConfig } from 'astro/config'

export default defineConfig({
  env: {
    schema: {
      // ...
    }
  }
})

Du kannst dann Variablen als String, Zahl, Enum oder Boolean mit dem envField-Helper registrieren. Definiere die Art der Umgebungsvariable, indem du einen context (Client oder Server) und einen access (geheim oder öffentlich) für jede Variable angibst, und übergebe alle zusätzlichen Eigenschaften wie optional oder default in einem Objekt:

import { defineConfig, envField } from 'astro/config'

export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({ context: "client", access: "public", optional: true }),
      PORT: envField.number({ context: "server", access: "public", default: 4321 }),
      API_SECRET: envField.string({ context: "server", access: "secret" }),
    }
  }
})

Die Typen werden für dich generiert, wenn du astro dev oder astro build ausführst. Du kannst aber auch astro sync ausführen, um nur Typen zu generieren.

Verwende Variablen aus deinem Schema

Importiere und verwende deine definierten Variablen aus dem entsprechenden /client oder /server Modul:

---
import { API_URL } from "astro:env/client"
import { API_SECRET_TOKEN } from "astro:env/server"

const data = await fetch(`${API_URL}/users`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_SECRET_TOKEN}`
  },
})
---

<script>
import { API_URL } from "astro:env/client"

fetch(`${API_URL}/ping`)
</script>

Variablentypen

Es gibt drei Arten von Umgebungsvariablen, die durch die Kombination von context (Client oder Server) und access (geheim oder öffentlich) in deinem Schema bestimmt werden:

Öffentliche Client-Variablen: Diese Variablen landen sowohl in deinem endgültigen Client- als auch in deinem Server-Bundle und können sowohl vom Client als auch vom Server über das Modul astro:env/client aufgerufen werden:
```
import { API_URL } from "astro:env/client"
```
Öffentliche Servervariablen: Diese Variablen landen in deinem endgültigen Server-Bundle und können auf dem Server über das Modul astro:env/server aufgerufen werden:
```
import { PORT } from "astro:env/server"
```
Geheime Servervariablen: Diese Variablen sind nicht Teil deines endgültigen Pakets und können auf dem Server über das Modul astro:env/server abgerufen werden:
```
import { API_SECRET } from "astro:env/server"
```
Standardmäßig werden Secrets nur zur Laufzeit überprüft. Du kannst die Validierung privater Variablen beim Start aktivieren, indem du validateSecrets: true (EN) konfigurierst.

Datentypen

Derzeit werden vier Datentypen unterstützt: Strings, Zahlen, Enums und Booleans:

import { envField } from "astro/config"

envField.string({
   // Kontext & Zugang
   optional: true,
   default: "foo",
})

envField.number({
   // Kontext & Zugang
   optional: true,
   default: 15,
})

envField.boolean({
   // Kontext & Zugang
   optional: true,
   default: true,
})

envField.enum({
   // Kontext & Zugang
   values: ['foo', 'bar', 'baz'],
   optional: true,
   default: 'baz',
})

Eine vollständige Liste der Validierungsfelder findest du in der envField API-Referenz (EN).

Dynamisches Abrufen von Secrets

Obwohl du dein Schema definiert hast, möchtest du vielleicht den Rohwert eines bestimmten Secrets abrufen oder Secrets abrufen, die nicht in deinem Schema definiert sind. In diesem Fall kannst du getSecret() verwenden, das von astro:env/server exportiert wird.

import {
   FOO, // boolean
   getSecret
} from 'astro:env/server'

getSecret('FOO') // string | undefined

Erfahre mehr in der API-Referenz (EN).

Einschränkungen

astro:env ist ein virtuelles Modul, das heißt, es kann nur innerhalb des Astro-Kontexts verwendet werden. Zum Beispiel kannst du es in
- Middlewares
- Astro-Routen und Endpunkte
- Astro-Komponenten
- Framework-Komponenten
- Modules
verwenden.

Du kannst sie im Folgenden nicht verwenden und musst auf process.env zurückgreifen:
- astro.config.mjs
- Skripte

@astrojs/cloudflare (EN) unterscheidet sich ein wenig von anderen Adaptern. Die Umgebungsvariablen sind auf die Anfrage beschränkt, im Gegensatz zu Node.js, wo sie global sind.

Das bedeutet, dass du Geheimnisse immer innerhalb des Anfragebereichs verwenden musst:

import { defineMiddleware } from "astro:middleware"
import { FOO, getSecret } from "astro:env"

console.log(FOO) // undefined
console.log(getSecret("FOO")) // undefined

export const onRequest = defineMiddleware((context, next) => {
   console.log(FOO) // boolean
   console.log(getSecret("FOO")) // string

   return next()
})

Wirke mit Community Sponsor