# Umgebung und Eigenschaften Elide lädt `.env`-Dateien als Standardwerte für die Umgebung der Anwendung und `.properties`-Dateien als Standardwerte für Java-Systemeigenschaften. Die Anwendung braucht keine Dotenv-Bibliothek. Beide Formate unterstützen dotenvx-kompatible verschlüsselte Werte. > [!NOTE] Verfügbar in Elide 1.6.2 > Diese Anleitung beschreibt die Unterstützung für den Ausführungskontext in Elide 1.6.2. ## Konfiguration laden Legen Sie `.env` in dem Verzeichnis an, aus dem Sie Elide aufrufen: ```dotenv APP_NAME=greeter APP_PORT=8080 APP_MESSAGE="Hello from ${APP_NAME}" ``` Legen Sie `app.ts` an: ```typescript console.log(process.env.APP_MESSAGE); console.log(process.env.APP_PORT); ``` ```sh elide run app.ts ``` ```text Hello from greeter 8080 ``` Eine geerbte Umgebungsvariable hat Vorrang, auch mit leerem Wert: ```sh APP_PORT=9090 elide run app.ts APP_PORT= elide run app.ts ``` Der zweite Aufruf erhält ein leeres `APP_PORT` statt `8080`. Lesen Sie Umgebungsvariablen über [`process.env`](/docs/env-variables), `os.environ` in Python oder die Umgebungsschnittstelle Ihrer Sprache. Auch Kindprozesse erhalten die wirksame Umgebung. Filtert eine Umgebungsrichtlinie geerbte Variablen, erben gestartete Java-Prozesse, Projekt-Tasks und Node-Kindprozesse nur den erlaubten Snapshot. Explizite Umgebungseinträge eines Tasks oder der JVM werden danach angewendet; eine explizite `env`-Map eines Node-Kindprozesses ersetzt die Vererbung. Das Laden von Dateien gewährt keine zusätzlichen Sandbox-Rechte und erweitert nicht den Umgebungszugriff eines Manifests; bestehende `--allow-env`-Regeln gelten weiterhin. ## Automatische Dateierkennung In jedem ausgewählten Verzeichnis liest Elide diese Dateien in dieser Reihenfolge: | Konfiguration | Zuerst | Danach, überschreibt die erste | | --- | --- | --- | | Umgebung | `.env` | `.env.local` | | Java-Properties | `.properties` | `.properties.local` | Fehlende automatische Dateien werden ignoriert. Vorhandene Dateien, die sich nicht lesen oder parsen lassen, führen zu einem Fehler. Die beiden Formate sind getrennt: Eine Umgebungsvariable namens `app.mode` setzt nicht die Java-Property `app.mode`. Standardmäßig prüft der Launcher nur das Aufrufverzeichnis. Der Speicherort eines Skripts ändert dieses Verzeichnis nicht. `elide run services/api/app.ts` wählt `services/api/.env` nicht automatisch aus. Mit `--project PATH` wählt Elide dieses Projektverzeichnis aus, oder das übergeordnete Verzeichnis, wenn `PATH` sein Manifest bezeichnet. Zuerst lädt es umschließende Verzeichnisse mit `elide.pkl`, vom äußersten zum innersten, dann das ausgewählte Verzeichnis. In jedem Verzeichnis folgt die lokale Datei auf die Basisdatei. Spätere Verzeichnisse überschreiben frühere. Beliebige Vorfahren, das Home-Verzeichnis und fremde Workspace-Mitglieder tragen keine Launcher-Konfiguration bei. ```sh elide --project services/api run app.ts ``` Projekt-Tasks nutzen außerdem ihre umschließenden, Workspace- und Mitglieds-Umgebungsebenen. Wählen Sie ein Projekt explizit aus, wenn seine umschließende Konfiguration beim Start verfügbar sein muss. Siehe [Projekteinrichtung](/docs/projects). Elide wählt `.env.production`, `.env.test`, `.properties.production` oder ähnliche Namen nicht automatisch aus. `NODE_ENV`, ein benanntes Ausführungsprofil und dotenvx-Profildateien wählen keine Konfigurationsdateien aus. Wählen Sie diese Dateien explizit. ## Dateien explizit wählen `--env-file` ersetzt die automatische Dotenv-Erkennung. `--properties-file` ersetzt unabhängig davon die automatische Properties-Erkennung. Wiederholen Sie eines der Flags, um Dateien zu schichten; bei doppelten Namen gewinnen spätere Argumente. Pfade sind relativ zum Aufrufverzeichnis, auch wenn `--project` angegeben ist. ```sh elide --env-file .env --env-file .env.production run app.ts elide --properties-file config/base.properties --properties-file config/production.properties run Main.java elide --env-file config/service.env --properties-file config/service.properties run Main.java ``` Explizite Dateien sind Pflicht: Eine fehlende Datei ist ein Fehler. Wird nur `.env.production` gewählt, werden `.env` und `.env.local` nicht zusätzlich geladen. Geben Sie jede gewünschte Datei an. | Flag | Wirkung | | --- | --- | | `--no-env` | Deaktiviert das Laden von Dotenv-Dateien. Geerbte Umgebungsvariablen bleiben verfügbar. | | `--no-properties` | Deaktiviert das Laden von Properties-Dateien. | | `--no-env --no-properties` | Deaktiviert beide Arten des Dateiladens. | ```sh elide --no-env --no-properties run app.ts ``` `--no-env` zusammen mit `--env-file` oder `--no-properties` zusammen mit `--properties-file` ist ein Bedienfehler. Sie können ein Format deaktivieren und für das andere explizit Dateien wählen. Eigenständig gestartete Java-Quelldateien berücksichtigen ebenfalls explizit gewählte Dateien, `--no-env` und `--no-properties`, ohne automatische Dateien erneut zu erkennen. ## Rangfolge Rangfolge der Umgebung, von niedrig nach hoch: 1. Ausgewählte Dotenv-Dateien, in Erkennungs- oder Argumentreihenfolge. 2. Geerbte Prozessumgebung, einschließlich leerer Werte. 3. Explizite Umgebungszuweisungen für einen bestimmten Task oder Kindprozess, innerhalb dieses Ausführungsbereichs. Rangfolge der Java-Properties, von niedrig nach hoch: 1. Ausgewählte Properties-Dateien, in Erkennungs- oder Argumentreihenfolge. 2. Vom Betreiber übergebene JVM-Zuweisungen mit `-D`, wenn Elide auf einer bestehenden JVM läuft. 3. Explizite Property-Zuweisungen in der Elide-CLI, etwa `--vm app.mode=production`. Von der VM bereitgestellte Property-Standardwerte zählen nicht als Betreiber-Zuweisungen. Anwendungen erhalten die Properties vor ihrer Initialisierung. Gestartete Java-Kindprozesse erhalten die Property-Standardwerte der Anwendung vor ihren eigenen expliziten JVM-Argumenten. Ein Task mit abweichenden VM-Properties läuft in einer separaten VM; seine Properties ändern nicht den globalen Zustand des Build-Treibers. ## Dotenv-Syntax Dotenv-Dateien unterstützen Kommentare, Werte in Anführungszeichen, mehrzeilige Werte, leere Werte und `${NAME}`-Interpolation. Einfache Anführungszeichen erhalten den Inhalt wörtlich. Doppelte Anführungszeichen erlauben Interpolation. ```dotenv # Application defaults APP_NAME=greeter APP_MESSAGE="Hello from ${APP_NAME}" APP_LITERAL='${APP_NAME}' APP_EMPTY= APP_MULTILINE="first line second line" APP_COMMAND='$(echo hello)' ``` `APP_LITERAL` ist die wörtliche Zeichenkette `${APP_NAME}`. `APP_COMMAND` ist die wörtliche Zeichenkette `$(echo hello)`; Elide führt in Konfigurationsdateien keine Shell-Befehlsersetzungen aus. Die Interpolation erfolgt beim Parsen jeder Datei. Sie kann geerbte Variablen und frühere Zuweisungen in derselben Datei verwenden. Sie wird nicht erneut ausgeführt, wenn spätere Dateien Werte überschreiben. Definiert `.env` `APP_NAME=greeter` und `APP_MESSAGE="Hello from ${APP_NAME}"` und ändert `.env.local` dann `APP_NAME` in `api`, lautet die Nachricht weiterhin `Hello from greeter`. Verlassen Sie sich nicht auf Interpolation über Dateigrenzen hinweg. ## Java-Properties Für Java- oder Kotlin-Anwendungen legen Sie `.properties` an: ```properties app.name=greeter app.message=Hello world app.empty= app.multiline=first\ second app.unicode=\u263A app.literal=${APP_NAME} ``` Lesen Sie diese in Java oder Kotlin mit `System.getProperty("app.name")`. Speichern Sie zum Beispiel `Main.java`: ```java class Main { public static void main(String[] args) { System.out.println(System.getProperty("app.message")); } } ``` ```sh elide run Main.java elide --vm app.message="Hello from the CLI" run Main.java ``` Der erste Aufruf gibt `Hello world` aus, der zweite `Hello from the CLI`. `app.multiline` ist `firstsecond`; `app.unicode` ist `☺`; `app.literal` bleibt `${APP_NAME}`. Properties verwenden Java-Syntax: Kommentare mit `#` und `!`, maskierte Trennzeichen, Fortsetzungszeilen und `\uXXXX`-Escapes. Anführungszeichen gehören zum Wert und sind keine Dotenv-Quotierung. Properties interpolieren keine Dotenv-Ausdrücke und führen keine Befehle aus. Für portablen Nicht-ASCII-Inhalt verwenden Sie Unicode-Escapes; der Properties-Reader dekodiert Bytes als Windows-1252. Property-Namen dürfen nicht leer sein und weder NUL noch `=` enthalten. Werte dürfen `=` enthalten, aber kein NUL. Die Property-Namensräume `java.*`, `elide*` und `org.graalvm*` sind eingeschränkt, außer `elide.diag.*`. Verschlüsselung umgeht diese Einschränkungen nicht. Einstellungen unter `polyglot.*` folgen dem Weg der Engine-Optionen. Verwenden Sie CLI-VM-Optionen für Einstellungen wie die Heap-Größe; eine Properties-Datei ist keine JVM-Argumentdatei. Läuft Elide auf einer bereits gestarteten JVM, liefert das Dateiladen Umgebungsebenen an Anwendungen und Kindprozesse. Es schreibt `System.getenv()` dieser JVM nicht um und ändert ihre Starteinstellungen nicht nachträglich. ## Verschlüsselte Werte Elide entschlüsselt dotenvx-kompatible `encrypted:`-Werte in Dotenv-Dateien und Java-Properties. Klartext- und verschlüsselte Werte können in derselben Datei stehen und folgen denselben Rangfolgeregeln. Ein verschlüsselter Wert, der durch einen späteren Klartextwert oder einen geerbten Umgebungswert ersetzt wird, braucht keinen Entschlüsselungsschlüssel. Erzeugen Sie Chiffretext mit einem kompatiblen Verschlüsselungswerkzeug. Elide übernimmt beim Laden der Konfiguration die Entschlüsselung, bietet aber keinen Verschlüsselungsbefehl. Zum Beispiel mit installiertem dotenvx: ```sh dotenvx encrypt -f .env.production elide --env-file .env.production run app.ts ``` Wählen Sie bei der Abfrage den lokalen `.env.keys`-Speicher von dotenvx. Sein [Verschlüsselungsablauf](https://dotenvx.com/docs/custody/env-keys/) behält den Chiffretext in der gewählten Dotenv-Datei und schreibt den privaten Schlüssel nach `.env.keys`. Für `.env.production` heißt der Schlüssel `DOTENV_PRIVATE_KEY_PRODUCTION`. Elide benötigt trotzdem `--env-file .env.production`; das Suffix des Schlüssels wählt die Datei nicht aus. ### Private Schlüssel bereitstellen Elide akzeptiert geerbte Variablen `DOTENV_PRIVATE_KEY` und `DOTENV_PRIVATE_KEY_*` mit Suffix oder Schlüssel in `.env.keys` neben den ausgewählten Konfigurationsquellen. Umgebung und Properties teilen sich dieselbe Schlüsselsuche. 1. Elide prüft `.env.keys` neben den ausgewählten Dotenv-Quellen, dann neben den ausgewählten Properties-Quellen, in Quellreihenfolge. Jedes Verzeichnis wird einmal geprüft; spätere Zuweisungen in Schlüsseldateien ersetzen frühere mit demselben Namen. 2. Geerbte `DOTENV_PRIVATE_KEY*`-Zuweisungen überschreiben gleichnamige Einträge aus Schlüsseldateien. 3. Die verfügbaren Schlüssel werden an den wirksamen verschlüsselten Werten ausprobiert. Ein Schlüsselsuffix beschränkt die Entschlüsselung nicht auf einen bestimmten Konfigurationsdateinamen. Schlüsseldateien werden nur gelesen, wenn ein wirksamer verschlüsselter Wert entschlüsselt werden muss. Ein Lauf nur mit Klartext braucht keine `.env.keys`. Die Schlüsselsuche durchsucht weder beliebige Vorfahren noch Ihr Home-Verzeichnis. Für CI übergeben Sie die passende Variable mit dem privaten Schlüssel über den Secret-Speicher der CI und führen Elide dann normal aus: ```sh # DOTENV_PRIVATE_KEY_PRODUCTION is supplied by the CI environment. elide --env-file .env.production run app.ts ``` Halten Sie `.env.keys` aus der Versionsverwaltung heraus, sichern Sie die Datei separat und beschränken Sie den Zugriff darauf. Prüfen Sie die Konfiguration vor dem Commit: Dass einige Werte verschlüsselt sind, heißt nicht, dass alle es sind. Geben Sie keine Anwendungsgeheimnisse aus und übergeben Sie keine privaten Schlüssel im Klartext in Shell-Befehlen und Logs. Einträge aus `.env.keys` dienen nur der Entschlüsselung; sie werden nicht zur Anwendungskonfiguration hinzugefügt. `DOTENV_PUBLIC_KEY*`-Einträge in Konfigurationsdateien sind Metadaten und werden aus den geladenen Anwendungswerten weggelassen. `DOTENV_PRIVATE_KEY*`-Zuweisungen in einer Dotenv- oder Properties-Datei der Anwendung sind ein Fehler. Geerbte Variablen mit privaten Schlüsseln unterliegen weiterhin der normalen Sichtbarkeit geerbter Umgebungsvariablen. ### Verschlüsselte Java-Properties Eine Java-Property kann einen kompatiblen Chiffretext ohne Anführungszeichen enthalten: ```properties app.secret=encrypted:... ``` Die Auslassungspunkte stehen für echten Chiffretext und sind kein gültiger verschlüsselter Wert. Elide parst zuerst die Java-Properties und entschlüsselt dann den dekodierten Wert mit denselben Schlüsseln wie bei Dotenv. Gehen Sie nicht davon aus, dass die dotenvx-CLI Java-Properties-Dateien parsen oder umschreiben kann. Entschlüsselter Text wird als Wert verwendet: Er wird weder erneut als Konfiguration geparst noch interpoliert oder ausgeführt. ## Befehle, Tests und Fehler Das automatische Laden gilt für `run`, `serve`, `dev`, `install`, `build`, `test`, `project`, `classpath`, `publish`, `java`, `python`, `repl` und die direkte Ausführung von Dateien. Hilfe, Version, Vervollständigungen und fremde Verwaltungsbefehle überspringen die automatische Konfigurationserkennung. Werkzeugbefehle wie `javac` und `kotlinc` laden diese Dateien nicht automatisch. Explizite Datei-Flags fordern das Laden der Konfiguration bei Befehlen an, die den Anwendungs-Launcher erreichen. Für reproduzierbare Tests wählen Sie Dateien explizit oder deaktivieren beide Formate: ```sh elide --env-file .env.test --no-properties test elide --no-env --no-properties test ``` Diese Flags löschen keine geerbten Umgebungsvariablen. Setzen oder entfernen Sie diese separat im Test-Runner. Ein aufgelöster Aufruf behält seinen Konfigurations-Snapshot; starten Sie einen neuen Aufruf, um geänderte Dateien oder Schlüssel zu übernehmen. Nicht lesbare ausgewählte Dateien, fehlerhafte Syntax, verbotene Einträge, ungültige Schlüssel und nicht entschlüsselbare wirksame Werte schlagen fehl, bevor die betreffende Anwendung oder der Task ausgeführt wird. Diagnosen melden eine Fehlerkategorie und den Quellpfad, ohne Quellzeilen, Werte, Chiffretext oder private Schlüssel auszugeben. Korrigieren Sie die gemeldete Quelle oder deaktivieren Sie ihr Format explizit. Eine teilweise aufgelöste Konfiguration aus einem fehlgeschlagenen Format wird nicht veröffentlicht. Zu Variablen, die Elide selbst konfigurieren, siehe [Laufzeit-Umgebungsvariablen](/docs/runtime-env-variables). Details zu den Flags: [CLI-Referenz](/docs/cli-references).