Umgebungsvariablen und Modi ​

Umgebungsvariablen ​

Vite stellt env-Variablen auf dem speziellen import.meta.env-Objekt zur Verfügung, die zur Erstellungszeit statisch ersetzt werden. Einige eingebaute Variablen sind in allen folgenden Fällen verfügbar:

• import.meta.env.MODE: {string} der Modus, in dem die App ausgeführt wird.

• import.meta.env.BASE_URL: {string} die Basis-URL, von der aus die App bereitgestellt wird. Dies wird durch die base Konfigurationsoption bestimmt.

• import.meta.env.PROD: {boolean} ob die App im Produktionsmodus läuft (wenn der Entwicklungsserver mit NODE_ENV='production' ausgeführt wird oder wenn eine App mit NODE_ENV='production' erstellt wird).

• import.meta.env.DEV: {boolean} ob die App im Entwicklungsmodus läuft (immer das Gegenteil von import.meta.env.PROD).

• import.meta.env.SSR: {boolean}, ob die Anwendung auf dem Server läuft.

.env Dateien ​

Vite verwendet dotenv, um zusätzliche Umgebungsvariablen aus den folgenden Dateien in Ihrem Umgebungsverzeichnis zu laden:

.env                # in allen Fällen geladen
.env.local          # in allen Fällen geladen, von Git ignoriert
.env.[mode]         # nur im angegebenen Modus geladen
.env.[mode].local   # nur im angegebenen Modus geladen, von Git ignoriert

Geladene Umgebungsvariablen werden auch Ihrem Client-Quellcode über import.meta.env als Zeichenfolgen zugänglich gemacht.

Um zu verhindern, dass Umgebungsvariablen versehentlich an den Client durchsickern, werden nur Variablen mit dem Präfix VITE_ in Ihrem von Vite verarbeiteten Code freigegeben. Zum Beispiel werden aus den folgenden Umgebungsvariablen:

VITE_SOME_KEY=123
DB_PASSWORD=foobar

nur VITE_SOME_KEY als import.meta.env.VITE_SOME_KEY in Ihrem Client-Quellcode freigegeben, aber DB_PASSWORD nicht.

console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined

Außerdem verwendet Vite dotenv-expand, um Variablen standardmäßig zu erweitern. Um mehr über die Syntax zu erfahren, werfen Sie einen Blick auf ihre Dokumentation.

Beachten Sie, dass Sie, wenn Sie $ in Ihrem Umgebungscode verwenden möchten, es mit \ escapen müssen.

KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123

Wenn Sie das Präfix für die Umgebungsvariablen ändern möchten, sehen Sie sich die envPrefix Option an.

IntelliSense für TypeScript ​

Standardmäßig stellt Vite Typdefinitionen für import.meta.env in vite/client.d.ts bereit. Obwohl Sie in .env.[mode]-Dateien weitere benutzerdefinierte Umgebungsvariablen definieren können, möchten Sie möglicherweise TypeScript IntelliSense für benutzerdefinierte Umgebungsvariablen erhalten, die mit VITE_ beginnen.

Um dies zu erreichen, können Sie eine vite-env.d.ts-Datei im src-Verzeichnis erstellen und ImportMetaEnv wie folgt erweitern:

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // mehr Umgebungsvariablen...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

Wenn Ihr Code auf Typen aus Browserumgebungen wie DOM und WebWorker angewiesen ist, können Sie das Feld lib in tsconfig.json aktualisieren.

{
  "lib": ["WebWorker"]
}

HTML-Umgebungsersatz ​

Vite unterstützt auch den Ersatz von Umgebungsvariablen in HTML-Dateien. Eigenschaften in import.meta.env können in HTML-Dateien mit einer speziellen %ENV_NAME%-Syntax verwendet werden:

<h1>Vite läuft im Modus %MODE%</h1>
<p>Verwendung von Daten von %VITE_API_URL%</p>

Wenn die Umgebung in import.meta.env nicht existiert, z.B. %NON_EXISTENT%, wird sie ignoriert und nicht ersetzt, im Gegensatz zu import.meta.env.NON_EXISTENT in JavaScript, wo sie als undefined ersetzt wird.

In Anbetracht der Tatsache, dass Vite von vielen Frameworks verwendet wird, ist es absichtlich nicht rechthaberisch gegenüber komplexen Ersetzungen wie Conditionals. Vite kann mit einem bereits bestehenden Userland-Plugin oder einem benutzerdefinierten Plugin, das den transformIndexHtml-Hook implementiert, erweitert werden.

Modi ​

Standardmäßig läuft der Entwicklungsserver (dev-Befehl) im development-Modus und der build-Befehl im production-Modus.

Dies bedeutet, dass bei Ausführung von vite build die Umgebungsvariablen aus .env.production geladen werden, wenn eine solche vorhanden ist:

# .env.production
VITE_APP_TITLE=Meine App

In Ihrer App können Sie den Titel mit import.meta.env.VITE_APP_TITLE rendern.

In einigen Fällen möchten Sie möglicherweise vite build mit einem anderen Modus ausführen, um einen anderen Titel zu rendern. Sie können den standardmäßig verwendeten Modus für einen Befehl überschreiben, indem Sie die Option --mode verwenden. Wenn Sie beispielsweise Ihre App für einen Staging-Modus erstellen möchten:

vite build --mode staging

Und erstellen Sie eine .env.staging-Datei:

# .env.staging
VITE_APP_TITLE=Meine App (staging)

Da vite build standardmäßig eine Produktionsversion erstellt, können Sie dies ebenfalls ändern und eine Entwicklungsversion erstellen, indem Sie einen anderen Modus und eine .env-Dateikonfiguration verwenden:

# .env.testing
NODE_ENV=development

NODE_ENV und Modi ​

Wichtig zu beachten ist, dass NODE_ENV (process.env.NODE_ENV) und Modi zwei verschiedene Konzepte sind. Hier sieht man, wie die verschiedenen Befehle die NODE_ENV und den Modus beeinflussen:

Die unterschiedlichen Werte von NODE_ENV und mode spiegeln sich auch in den entsprechenden Eigenschaften von import.meta.env wider: