Variables y modos de entorno
Variables de Entorno
Vite expone variables de entorno en el objeto especial import.meta.env
, que se reemplazan estáticamente en tiempo de compilación. Algunas variables integradas están disponibles en todos los casos:
import.meta.env.MODE
: {string} el modo en el que se ejecuta la aplicación.import.meta.env.BASE_URL
: {string} la URL base desde la que se sirve la aplicación. Esto está determinado por la opción de configuraciónbase
.import.meta.env.PROD
: {boolean} si la aplicación se ejecuta en producción (ejecutando el servidor de desarrollo conNODE_ENV='production'
o ejecutando una aplicación compilada conNODE_ENV='production'
).import.meta.env.DEV
: {boolean} si la aplicación se está ejecutando en desarrollo (siempre lo contrario deimport.meta.env.PROD
)import.meta.env.SSR
: {boolean} si la aplicación se ejecuta en el servidor.
Archivos .env
Vite usa dotenv para cargar variables de entorno adicionales desde los siguientes archivos en su directorio de entorno:
.env # cargado en todos los casos
.env.local # cargado en todos los casos, ignorado por git
.env.[mode] # solo se carga en el modo especificado
.env.[mode].local # solo se carga en el modo especificado, ignorado por git
Prioridades de carga
Un archivo env para un modo específico (por ejemplo, .env.production
) tendrá mayor prioridad que uno genérico (por ejemplo, .env
).
Además, las variables de entorno que ya existen cuando se ejecuta Vite tienen la prioridad más alta y no serán sobrescritas por los archivos .env
. Por ejemplo, al ejecutar VITE_SOME_KEY=123 vite build
.
Los archivos .env
se cargan al inicio de Vite. Reinicia el servidor después de realizar cambios.
Las variables de entorno cargadas también se exponen al código fuente del cliente a través de import.meta.env
como cadenas.
Para evitar la filtración accidental de variables de entorno al cliente, solo las variables con el prefijo VITE_
se exponen a su código procesado por Vite, por ejemplo, las siguientes variables de entorno:
VITE_SOME_KEY=123
DB_PASSWORD=foobar
Solo VITE_SOME_KEY
se expondrá como import.meta.env.VITE_SOME_KEY
en el código fuente del cliente, pero DB_PASSWORD
no.
console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined
Análisis de Env
Como se muestra anteriormente, VITE_SOME_KEY
es un número pero devuelve una cadena cuando se analiza. Lo mismo ocurriría también para variables de entorno booleanas. Asegúrate de convertir al tipo deseado al usarlo en tu código.
Además, Vite usa dotenv-expand para expandir variables listas para usar. Para obtener más información sobre la sintaxis, consulta su documentación.
Ten en cuenta que si deseas usar $
dentro del valor de la variable de entorno, debe escapar con \
.
KEY=123
NEW_KEY1=test$foo # test
NEW_KEY2=test\$foo # test$foo
NEW_KEY3=test$KEY # test123
Si deseas personalizar el prefijo de las variables env, consulta la opción envPrefix.
NOTAS DE SEGURIDAD
Los archivos
.env.*.local
son solo locales y pueden contener variables confidenciales. Debes agregar*.local
al.gitignore
para evitar que se registren en git.Dado que cualquier variable expuesta al código fuente de Vite terminará en el paquete de cliente, las variables
VITE_*
no deberían contener información confidencial.
IntelliSense para TypeScript
De forma predeterminada, Vite proporciona definiciones de tipo para import.meta.env
en vite/client.d.ts
. Si bien puedes definir más variables de entorno personalizadas en los archivos .env.[mode]
, es posible que desees que IntelliSense funcione para las variables de entorno definidas por el usuario que tienen el prefijo VITE_
.
Para hacerlo, puedes crear un vite-env.d.ts
en el directorio src
, luego extender ImportMetaEnv
de esta manera:
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_APP_TITLE: string
// más variables de entorno...
}
interface ImportMeta {
readonly env: ImportMetaEnv
}
Si tu código se basa en tipos de entornos de navegador como DOM y WebWorker, puedes actualizar el campo lib en el tsconfig.json
.
{
"lib": ["WebWorker"]
}
Las importaciones romperán la augmentación de tipo
Si la augmentación de ImportMetaEnv
no funciona, asegúrate de que no haya ninguna declaración de import
en vite-env.d.ts
. Consulta la documentación de TypeScript para obtener más información.
Sustitución de variables de entorno en archivos HTML
Vite también admite la sustitución de variables de entorno en archivos HTML. Cualquier propiedad en import.meta.env
se puede usar en archivos HTML con una sintaxis especial %ENV_NAME%
:
<h1>Vite se está ejecutando en %MODE%</h1>
<p>Usando datos desde %VITE_API_URL%</p>
Si el entorno no existe en import.meta.env
, por ejemplo, %NON_EXISTENT%
, se ignorará y no se reemplazará, a diferencia de import.meta.env.NON_EXISTENT
en JS, donde se reemplaza como undefined
.
Dado que Vite es utilizado por muchos frameworks, está intencionalmente diseñado sin preferencias establecidad sobre reemplazos complejos como, por ejemplo, los condicionales. Vite puede ser extendido utilizando un plugin existente en el ámbito de usuario o un plugin personalizado que implemente el hook transformIndexHtml
.
Modos
De forma predeterminada, el servidor de desarrollo (comando dev
) se ejecuta en modo development
y los comandos build
y serve
se ejecutan en modo production
.
Esto significa que al ejecutar vite build
, cargará las variables de entorno de .env.production
si hay una:
# .env.production
VITE_APP_TITLE=My App
En tu aplicación, puedes representar el título usando import.meta.env.VITE_APP_TITLE
.
En algunos casos, es posible que desees ejecutar vite build
con un modo distinto para renderizar un título diferente. Puedes sobrescribir el modo predeterminado utilizado para un comando pasando el indicador de opción --mode
. Por ejemplo, si deseas crear una aplicación para un modo staging:
vite build --mode staging
Y luego crea un archivo .env.staging
:
# .env.staging
NODE_ENV=production
VITE_APP_TITLE=My App (staging)
Como vite build
ejecuta una compilación en producción de forma predeterminada, también puedes modificar y ejecutar una compilación en desarrollo usando un modo diferente y un archivo de configuración .env
:
# .env.testing
NODE_ENV=development
NODE_ENV y Modos
Es importante tener en cuenta que NODE_ENV
(process.env.NODE_ENV
) y los modos son dos conceptos diferentes. Así es cómo afectan a NODE_ENV
y al modo diferentes comandos:
Comando | NODE_ENV | Modo |
---|---|---|
vite build | "production" | "production" |
vite build --mode development | "production" | "development" |
NODE_ENV=development vite build | "development" | "production" |
NODE_ENV=development vite build --mode development | "development" | "development" |
Los diferentes valores de NODE_ENV
y modo también se reflejan en sus propiedades correspondientes de import.meta.env
:
Comando | import.meta.env.PROD | import.meta.env.DEV |
---|---|---|
NODE_ENV=production | true | false |
NODE_ENV=development | false | true |
NODE_ENV=other | false | true |
Comando | import.meta.env.MODE |
---|---|
--mode production | "production" |
--mode development | "development" |
--mode staging | "staging" |
NODE_ENV
en archivos .env
NODE_ENV=...
se puede configurar en el comando y también en tu archivo .env
. Si NODE_ENV
está especificado en un archivo .env.[modo]
, el modo se puede utilizar para controlar su valor. Sin embargo, tanto NODE_ENV
como los modos siguen siendo dos conceptos diferentes. El principal beneficio con NODE_ENV=...
en el comando es que permite que Vite detecte el valor temprano. También te permite leer process.env.NODE_ENV
en tu configuración de Vite, ya que Vite solo puede cargar los archivos env una vez que se evalúa la configuración.