Variables de entorno de Vite

Variables y patrones ambientales.

Variable ambiental

Vite expone variables de entorno en un objeto especial import.meta.env. A continuación se muestran algunas variables integradas que se pueden utilizar en todos los casos:

import.meta.env.MODE: {string} 应用运行的模式。

import.meta.env.BASE_URL: {string} 部署应用时的基本 URL。他由base 配置项决定。

import.meta.env.PROD: {boolean} 应用是否运行在生产环境。

import.meta.env.DEV: {boolean} 应用是否运行在开发环境 (永远与 import.meta.env.PROD相反)。

import.meta.env.SSR: {boolean} 应用是否运行在 server 上。

Reemplazo del entorno de producción

En producción, estas variables de entorno se reemplazan estáticamente en el momento de la compilación, por lo tanto, utilice cadenas completamente estáticas al hacer referencia a ellas. Las claves dinámicas no tendrán efecto. Por ejemplo, el valor de clave dinámica import.meta.env[key] no es válido.

También reemplazará las cadenas que aparecen en las plantillas de JavaScript y Vue. Esto debería ser muy raro, pero podría haberse hecho accidentalmente. En este caso, es posible que vea errores como Falta punto y coma o Token inesperado, por ejemplo, cuando "process.env.NODE_ENV" se reemplaza con ""desarrollo": ". Hay algunas formas de evitar este problema:

Para cadenas de JavaScript, puede utilizar espacios Unicode de ancho cero para dividir la cadena, por ejemplo: 'import.meta\u200b.env.MODE'.

Para plantillas de Vue u otro HTML compilado en cadenas de JavaScript, puede usar la etiqueta, por ejemplo: import.meta.env.MODE .

Archivos .env
Vite usa dotenv para cargar variables de entorno adicionales desde los siguientes archivos en su directorio de entorno:

.env                # 所有情况下都会加载
.env.local          # 所有情况下都会加载，但会被 git 忽略
.env.[mode]         # 只在指定模式下加载
.env.[mode].local   # 只在指定模式下加载，但会被 git 忽略\

Prioridad de carga del entorno

Un archivo que especifica un esquema (por ejemplo, .env.production) tiene prioridad sobre una forma genérica (por ejemplo, .env).

Además, las variables de entorno que ya existen cuando se ejecuta Vite tienen la máxima prioridad y no serán sobrescritas por el archivo de clase .env. Por ejemplo, cuando ejecuta VITE_SOME_KEY=123 vite build.

El archivo de clase .env se cargará al comienzo del inicio de Vite y los cambios entrarán en vigor después de reiniciar el servidor.

Las variables de entorno cargadas también se exponen al código fuente del cliente como cadenas a través de import.meta.env.

为了防止意外地将一些环境变量泄漏到客户端，只有以 VITE_ 为前缀的变量才会暴露给经过 vite 处理的代码`. Por ejemplo, las siguientes variables de entorno:

VITE_SOME_KEY=123
DB_PASSWORD=foobar
只有 VITE_SOME_KEY 会被暴露为 import.meta.env.VITE_SOME_KEY 提供给客户端源码，而 DB_PASSWORD 则不会。

console.log(import.meta.env.VITE_SOME_KEY) // 123
console.log(import.meta.env.DB_PASSWORD) // undefined
此外，Vite 使用 dotenv-expand 来直接拓展变量。想要了解更多相关语法，请查看 它们的文档。

Tenga en cuenta que si desea utilizar el símbolo $ en una 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 desea personalizar el prefijo de las variables env, consulte envPrefix .

Precauciones de seguridad

Los archivos .env.*.local deben ser locales y pueden contener variables confidenciales. Debes agregar .local a tu .gitignore para evitar que git los registre.

Dado que cualquier variable expuesta al código fuente de Vite eventualmente aparecerá en el paquete del cliente, las variables VITE_* no deben contener ninguna información confidencial.

IntelliSense para TypeScript
De forma predeterminada, Vite proporciona definiciones de tipos para import.meta.env en vite/client.d.ts. A medida que personaliza más y más variables de entorno en sus archivos .env[mode], es posible que desee obtener TypeScript intellisense para esas variables de entorno definidas por el usuario con el prefijo VITE_ en su código.

Para hacer esto, puede crear un archivo env.d.ts en el directorio src y luego agregar la definición ImportMetaEnv de la siguiente manera:

/// <reference types="vite/client" />

interface ImportMetaEnv {
    
    
  readonly VITE_APP_TITLE: string
  // 更多环境变量...
}

interface ImportMeta {
    
    
  readonly env: ImportMetaEnv
}

Si su código depende del tipo de entorno del navegador, como DOM y WebWorker, puede modificar el campo lib en tsconfig.json para obtener compatibilidad con tipos.

{
    
    
  "lib": ["WebWorker"]
}

Modos
De forma predeterminada, el servidor de desarrollo (comando dev) se ejecuta en modo de desarrollo y el comando de compilación se ejecuta en modo de producción.

Esto significa que cuando se ejecuta vite build, cargará automáticamente las variables de entorno que puedan existir en .env.production:

.env.producción

VITE_APP_TITLE=Mi aplicación
En su aplicación, puede usar import.meta.env.VITE_APP_TITLE para representar el título.

En algunos casos, si desea ejecutar vite build en un modo diferente para representar títulos diferentes, puede anular el modo predeterminado utilizado por el comando pasando la opción --mode. Por ejemplo, si desea crear su aplicación en modo de prueba (prelanzamiento):

bash
vite build --mode staging
también necesita crear un nuevo archivo .env.staging:

.env.puesta en escena

VITE_APP_TITLE=Mi aplicación (ensayo)
Dado que vite build ejecuta compilaciones en modo de producción de forma predeterminada, también puede cambiarlo para ejecutar compilaciones en modo de desarrollo usando un modo diferente y la configuración del archivo .env correspondiente:

.env.pruebas

NODE_ENV=desarrollo