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.

Konfiguration laden

Legen Sie .env in dem Verzeichnis an, aus dem Sie Elide aufrufen:

APP_NAME=greeter
APP_PORT=8080
APP_MESSAGE="Hello from ${APP_NAME}"

Legen Sie app.ts an:

console.log(process.env.APP_MESSAGE);
console.log(process.env.APP_PORT);

elide run app.ts

Hello from greeter
8080

Eine geerbte Umgebungsvariable hat Vorrang, auch mit leerem Wert:

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, 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:

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.

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.

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.

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.

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.

# 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:

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:

class Main {
  public static void main(String[] args) {
    System.out.println(System.getProperty("app.message"));
  }
}

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:

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 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:

# 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:

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:

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. Details zu den Flags: CLI-Referenz.