Entorno y propiedades

Elide carga los archivos .env como valores predeterminados del entorno de la aplicación y los archivos .properties como valores predeterminados de las propiedades del sistema Java. No se necesita ninguna biblioteca dotenv en la aplicación. Ambos formatos admiten valores cifrados compatibles con dotenvx.

Cargar la configuración

Cree .env en el directorio desde el que invoca Elide:

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

Cree app.ts:

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

elide run app.ts

Hello from greeter
8080

Una variable de entorno heredada tiene prioridad, incluso si su valor está vacío:

APP_PORT=9090 elide run app.ts
APP_PORT= elide run app.ts

La segunda invocación recibe un APP_PORT vacío, en lugar de 8080. Lea las variables de entorno mediante process.env, os.environ de Python o la interfaz de entorno de su lenguaje. Los procesos hijo también reciben el entorno efectivo. Cuando una política de entorno filtra las variables heredadas, los procesos Java lanzados, las tareas del proyecto y los procesos hijo de Node heredan solo la instantánea permitida. Las entradas de entorno explícitas de una tarea o de la JVM se aplican después; un mapa env explícito de un proceso hijo de Node sustituye la herencia. La carga de archivos no concede capacidades adicionales del sandbox ni amplía el acceso al entorno de un manifiesto; los controles --allow-env existentes siguen aplicándose.

Descubrimiento automático de archivos

En cada directorio seleccionado, Elide lee estos archivos en orden:

Los archivos automáticos que faltan se ignoran. Los archivos existentes que no se pueden leer o analizar provocan un error. Los dos formatos son independientes: una variable de entorno llamada app.mode no define la propiedad Java app.mode.

De forma predeterminada, el lanzador solo revisa el directorio de invocación. La ubicación de un script no cambia ese directorio. Ejecutar elide run services/api/app.ts no selecciona automáticamente services/api/.env.

Con --project PATH, Elide selecciona ese directorio de proyecto, o su directorio padre cuando PATH apunta a su manifiesto. Primero carga los directorios contenedores que tienen elide.pkl, del más externo al más interno, y luego el directorio seleccionado. En cada directorio, el archivo local va después del archivo base. Los directorios posteriores sobrescriben a los anteriores. Los ancestros arbitrarios, el directorio personal y los miembros no relacionados del espacio de trabajo no aportan configuración al lanzador.

elide --project services/api run app.ts

Las tareas del proyecto también usan sus capas de entorno contenedoras, del espacio de trabajo y del miembro. Seleccione un proyecto explícitamente cuando su configuración contenedora deba estar disponible al inicio. Consulte Configurar un proyecto.

Elide no selecciona automáticamente .env.production, .env.test, .properties.production ni nombres similares. NODE_ENV, un perfil de ejecución con nombre y los archivos de perfil de dotenvx no seleccionan archivos de configuración. Elija estos archivos explícitamente.

Elegir archivos explícitamente

--env-file sustituye el descubrimiento automático de dotenv. --properties-file sustituye, de forma independiente, el descubrimiento automático de propiedades. Repita cualquiera de las dos opciones para superponer archivos; los argumentos posteriores ganan cuando hay nombres duplicados. Las rutas son relativas al directorio de invocación, también cuando se indica --project.

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

Los archivos explícitos son obligatorios: un archivo que falta es un error. Seleccionar solo .env.production no carga también .env ni .env.local. Incluya cada archivo que necesite.

elide --no-env --no-properties run app.ts

Combinar --no-env con --env-file, o --no-properties con --properties-file, es un error de uso. Puede desactivar un formato y seleccionar explícitamente archivos para el otro.

Los lanzamientos de código fuente Java independiente también respetan las selecciones explícitas de archivos, --no-env y --no-properties, sin volver a descubrir archivos automáticos.

Precedencia

Precedencia del entorno, de menor a mayor:

1. Archivos dotenv seleccionados, en orden de descubrimiento o de argumentos.
2. Entorno heredado del proceso, incluidos los valores vacíos.
3. Asignaciones de entorno explícitas para una tarea o un proceso hijo concretos, dentro de ese ámbito de ejecución.

Precedencia de las propiedades Java, de menor a mayor:

1. Archivos de propiedades seleccionados, en orden de descubrimiento o de argumentos.
2. Asignaciones -D de la JVM indicadas por el operador cuando Elide se ejecuta en una JVM existente.
3. Asignaciones explícitas de propiedades en la CLI de Elide, como --vm app.mode=production.

Los valores predeterminados de propiedades que aporta la VM no cuentan como asignaciones del operador. Las aplicaciones reciben las propiedades antes de su inicialización. Los lanzamientos Java hijo reciben los valores predeterminados de propiedades de la aplicación antes de sus propios argumentos explícitos de la JVM. Una tarea con propiedades de VM distintas se ejecuta en una VM aparte; sus propiedades no cambian el estado global del controlador de compilación.

Sintaxis de dotenv

Los archivos dotenv admiten comentarios, valores entre comillas, valores multilínea, valores vacíos e interpolación ${NAME}. Las comillas simples conservan el contenido literal. Las comillas dobles permiten la interpolación.

# 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 es la cadena literal ${APP_NAME}. APP_COMMAND es la cadena literal $(echo hello); Elide no ejecuta sustituciones de comandos de shell en los archivos de configuración.

La interpolación ocurre mientras se analiza cada archivo. Puede usar variables heredadas y asignaciones anteriores del mismo archivo. No se vuelve a ejecutar después de que archivos posteriores sobrescriban valores. Si .env define APP_NAME=greeter y APP_MESSAGE="Hello from ${APP_NAME}", y luego .env.local cambia APP_NAME a api, el mensaje sigue siendo Hello from greeter. No dependa de la interpolación entre archivos distintos.

Propiedades Java

Para aplicaciones Java o Kotlin, cree .properties:

app.name=greeter
app.message=Hello world
app.empty=
app.multiline=first\
  second
app.unicode=\u263A
app.literal=${APP_NAME}

Léalas con System.getProperty("app.name") en Java o Kotlin. Por ejemplo, guarde 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

La primera invocación imprime Hello world; la segunda imprime Hello from the CLI. app.multiline vale firstsecond; app.unicode vale ☺; app.literal sigue siendo ${APP_NAME}.

Las propiedades usan la sintaxis de Java: comentarios con # y !, separadores escapados, líneas de continuación y escapes \uXXXX. Las comillas forman parte del valor; no son comillas de dotenv. Las propiedades no interpolan expresiones de dotenv ni ejecutan comandos. Para contenido no ASCII portable, use escapes Unicode; el lector de propiedades decodifica los bytes como Windows-1252.

Los nombres de propiedad no pueden estar vacíos ni contener NUL ni =. Los valores pueden contener =, pero no NUL. Los espacios de nombres de propiedades java.*, elide* y org.graalvm* están restringidos, salvo elide.diag.*. El cifrado no evita estas restricciones. Los ajustes polyglot.* siguen la ruta de las opciones del motor. Use las opciones de VM de la CLI para ajustes como el tamaño del heap; un archivo de propiedades no es un archivo de argumentos de la JVM.

Cuando Elide se ejecuta en una JVM ya iniciada, la carga de archivos aporta capas de entorno a las aplicaciones y a los procesos hijo. No reescribe System.getenv() de esa JVM ni cambia retroactivamente su configuración de inicio.

Valores cifrados

Elide descifra los valores encrypted: compatibles con dotenvx en archivos dotenv y propiedades Java. Los valores en texto plano y cifrados pueden aparecer en el mismo archivo y siguen las mismas reglas de precedencia. Un valor cifrado que se sustituye por un valor posterior en texto plano, o por un valor heredado del entorno, no necesita clave de descifrado.

Use una herramienta de cifrado compatible para generar el texto cifrado. Elide se encarga del descifrado al cargar la configuración; no proporciona un comando de cifrado. Por ejemplo, con dotenvx instalado:

dotenvx encrypt -f .env.production
elide --env-file .env.production run app.ts

Elija el almacenamiento local .env.keys de dotenvx cuando se le pregunte. Su flujo de cifrado guarda el texto cifrado en el archivo dotenv seleccionado y escribe la clave privada en .env.keys. Para .env.production, la clave se llama DOTENV_PRIVATE_KEY_PRODUCTION. Elide sigue necesitando --env-file .env.production; el sufijo de la clave no selecciona el archivo.

Proporcionar claves privadas

Elide acepta las variables heredadas DOTENV_PRIVATE_KEY y DOTENV_PRIVATE_KEY_* con sufijo, o claves en .env.keys junto a las fuentes de configuración seleccionadas. El entorno y las propiedades comparten la misma búsqueda de claves.

1. Elide revisa .env.keys junto a las fuentes dotenv seleccionadas y luego junto a las fuentes de propiedades seleccionadas, en orden de fuente. Cada directorio se revisa una vez; las asignaciones posteriores de archivos de claves sustituyen a las anteriores con el mismo nombre.
2. Las asignaciones heredadas DOTENV_PRIVATE_KEY* sobrescriben los nombres coincidentes de los archivos de claves.
3. Las claves disponibles se prueban con los valores cifrados efectivos. Un sufijo de clave no limita el descifrado a un nombre de archivo de configuración concreto.

Los archivos de claves solo se leen cuando un valor cifrado efectivo necesita descifrarse. Una ejecución solo con texto plano no requiere .env.keys. La búsqueda de claves no recorre ancestros arbitrarios ni su directorio personal.

En CI, inyecte la variable de clave privada correspondiente mediante el almacén de secretos de CI y ejecute Elide con normalidad:

# DOTENV_PRIVATE_KEY_PRODUCTION is supplied by the CI environment.
elide --env-file .env.production run app.ts

Mantenga .env.keys fuera del control de versiones, haga una copia de seguridad aparte y limite el acceso al archivo. Revise la configuración antes de versionarla: que algunos valores estén cifrados no significa que lo estén todos. Evite imprimir secretos de la aplicación o pasar claves privadas literales en comandos de shell y registros.

Las entradas de .env.keys solo se usan para descifrar; no se añaden a la configuración de la aplicación. Las entradas DOTENV_PUBLIC_KEY* de los archivos de configuración son metadatos y se omiten de los valores cargados en la aplicación. Poner asignaciones DOTENV_PRIVATE_KEY* en un archivo dotenv o de propiedades de la aplicación es un error. Las variables de clave privada heredadas siguen sujetas a la visibilidad normal del entorno heredado.

Propiedades Java cifradas

Una propiedad Java puede contener un valor cifrado compatible sin comillas:

app.secret=encrypted:...

Los puntos suspensivos sustituyen al texto cifrado real; no son un valor cifrado válido. Elide analiza primero las propiedades Java y luego descifra el valor decodificado con las mismas claves que dotenv. No suponga que la CLI de dotenvx puede analizar o reescribir archivos de propiedades Java. El texto descifrado se usa como valor: no se vuelve a analizar como configuración, ni se interpola, ni se ejecuta.

Comandos, pruebas y errores

La carga automática se aplica a run, serve, dev, install, build, test, project, classpath, publish, java, python, repl y a la ejecución directa de archivos. La ayuda, la versión, los autocompletados y los comandos administrativos no relacionados omiten el descubrimiento automático de configuración. Los comandos de herramientas como javac y kotlinc no cargan estos archivos automáticamente. Las opciones explícitas de archivo solicitan la carga de configuración en los comandos que llegan al lanzador de la aplicación.

Para pruebas reproducibles, elija los archivos explícitamente o desactive ambos formatos:

elide --env-file .env.test --no-properties test
elide --no-env --no-properties test

Estas opciones no borran las variables de entorno heredadas. Defínalas o elimínelas por separado en el ejecutor de pruebas. Una invocación resuelta conserva su instantánea de configuración; inicie una invocación nueva para recoger archivos o claves modificados.

Los archivos seleccionados ilegibles, la sintaxis mal formada, las entradas prohibidas, las claves no válidas y los valores efectivos que no se pueden descifrar fallan antes de que se ejecute la aplicación o la tarea correspondiente. Los diagnósticos informan de una categoría de error y de la ruta de origen sin imprimir líneas de origen, valores, texto cifrado ni claves privadas. Corrija la fuente indicada o desactive explícitamente su formato. No se publica ninguna configuración parcialmente resuelta de un formato que haya fallado.

Para las variables que configuran el propio Elide, consulte Variables de entorno del runtime. Para los detalles de las opciones, consulte Referencia CLI.