import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro';import ReadMore from '/components/ReadMore.astro';

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 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=password123PUBLIC_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.

:::caution .env-Dateien werden nicht innerhalb von Konfigurations­dateien geladen. :::

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 Konfigurations­option base bestimmt.
• import.meta.env.SITE: Diese wird auf die Option site gesetzt, die in der astro.config deines Projekts angegeben ist. {/* TODO: update anchor link (#buildassetsprefix) when the linked file has been updated */}
• import.meta.env.ASSETS_PREFIX: Das Präfix für die von Astro erzeugten Asset-Links, wenn die Konfigurations­option build.assetsPrefix 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 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 istastro dev --mode staging# Baue eine Website, die sich mit einer „Produktions“-API mit zusätzlichen Debug-Informationen verbindetastro build --devOutput# Erstelle eine Website, die sich mit einer „Test“-API verbindetastro build --mode testing

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

In der Astro-Konfigurationsdatei

Astro wertet die Konfigurations­dateien 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(), "");

:::note 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 Kommandozeilen­schnittstelle (CLI)

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

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 === trueconst data = await db(import.meta.env.DB_PASSWORD);// Wenn import.meta.env.SSR === falseconst 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 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.

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:

  js

  Code kopieren

  Kopieren Sie den Code in die Zwischenablage

  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:

  js

  Code kopieren

  Kopieren Sie den Code in die Zwischenablage

  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:

  js

  Code kopieren

  Kopieren Sie den Code in die Zwischenablage

  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 konfigurierst.

:::note Geheime Client-Variablen werden nicht unterstützt, da es keine sichere Möglichkeit gibt, diese Daten an den Client zu senden. Daher ist es nicht möglich, sowohl context: "client" und access: "secret" in deinem Schema zu konfigurieren. :::

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.

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.

Einschränkungen

1. 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

2. @astrojs/cloudflare 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:

   js

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { defineMiddleware } from "astro:middleware"import { FOO, getSecret } from "astro:env"console.log(FOO) // undefinedconsole.log(getSecret("FOO")) // undefinedexport const onRequest = defineMiddleware((context, next) => {   console.log(FOO) // boolean   console.log(getSecret("FOO")) // string   return next()})