# 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. > [!NOTE] Disponible en Elide 1.6.2 > Esta guía describe la compatibilidad con el contexto de ejecución de Elide 1.6.2. ## Cargar la configuración Cree `.env` en el directorio desde el que invoca Elide: ```dotenv APP_NAME=greeter APP_PORT=8080 APP_MESSAGE="Hello from ${APP_NAME}" ``` Cree `app.ts`: ```typescript console.log(process.env.APP_MESSAGE); console.log(process.env.APP_PORT); ``` ```sh elide run app.ts ``` ```text Hello from greeter 8080 ``` Una variable de entorno heredada tiene prioridad, incluso si su valor está vacío: ```sh 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`](/docs/env-variables), `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: | Configuración | Primero | Segundo, que sobrescribe el primero | | --- | --- | --- | | Entorno | `.env` | `.env.local` | | Propiedades Java | `.properties` | `.properties.local` | 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. ```sh 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](/docs/projects). 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`. ```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 ``` 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. | Opción | Efecto | | --- | --- | | `--no-env` | Desactiva la carga de dotenv. Las variables de entorno heredadas siguen disponibles. | | `--no-properties` | Desactiva la carga de archivos de propiedades. | | `--no-env --no-properties` | Desactiva ambos tipos de carga de archivos. | ```sh 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. ```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` 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`: ```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`: ```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 ``` 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: ```sh 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](https://dotenvx.com/docs/custody/env-keys/) 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: ```sh # 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: ```properties 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: ```sh 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](/docs/runtime-env-variables). Para los detalles de las opciones, consulte [Referencia CLI](/docs/cli-references).