Variáveis e Modos de Ambiente

Variáveis de Ambiente

A Vite expõe as variáveis de ambiente sobre o objeto especial import.meta.env. Algumas variáveis embutidas estão disponíveis em todos os casos:

• import.meta.env.MODE: {sequência de caracteres} o modo no qual a aplicação executa.

• import.meta.env.BASE_URL: {sequência de caracteres} a URL de base a partir da qual a aplicação é servida. Isto é determinado pela opção de configuração base.

• import.meta.env.PROD: {booleano} se a aplicação executa em produção (executa o servidor de desenvolvimento com NODE_ENV='production' ou executa uma aplicação construída com NODE_ENV='production').

• import.meta.env.DEV: {booleano} se a aplicação executa em desenvolvimento (sempre o oposto de import.meta.env.PROD)

• import.meta.env.SSR: {booleano} se a aplicação executa no servidor.

Os Ficheiros .env

A Vite usa o pacote dotenv para carregar as variáveis de ambiente adicionais a partir dos seguintes ficheiros no diretório do nosso ambiente:

.env                # carregado em todos os casos
.env.local          # carregado em todos os casos, mas ignorado pelo git
.env.[mode]         # carregado apenas no modo especificado
.env.[mode].local   # carregado apenas no modo especificado, mas ignorado pelo git

.env                # carregado em todos os casos
.env.local          # carregado em todos os casos, mas ignorado pelo git
.env.[mode]         # carregado apenas no modo especificado
.env.[mode].local   # carregado apenas no modo especificado, mas ignorado pelo git

PRIORIDADES DE CARREGAMENTO DO AMBIENTE

Um ficheiro de ambiente para um modo específico (por exemplo, .env.production) receberá prioridade superior à um genérico (por exemplo, .env).

Além disto, as variáveis de ambiente que já existiam quando a Vite for executada têm a prioridade muito superior e não serão sobrescritas pelos ficheiros .env. Por exemplo, quando executamos VITE_SOME_KEY=123 vite build.

Os ficheiros .env são carregados durante a inicialização da Vite. Reinicia o servidor depois de fazermos mudanças.

As variáveis de ambiente carregadas também são expostas ao nosso código-fonte do nosso cliente através de import.meta.env como sequências de caracteres.

Para evitar que acidentalmente vazemos as variáveis de ambiente para o cliente, apenas as variáveis prefixadas com VITE_ são expostas ao nosso código processado pela Vite. Por exemplo, para as seguintes variáveis de ambiente:

VITE_SOME_KEY=123
DB_PASSWORD=foobar

VITE_SOME_KEY=123
DB_PASSWORD=foobar

Apenas VITE_SOME_KEY será exposta como import.meta.env.VITE_SOME_KEY ao código-fonte do nosso cliente, mas DB_PASSWORD não será exposta:

console.log(import.meta.env.VITE_SOME_KEY) // 123
console.log(import.meta.env.DB_PASSWORD) // undefined

console.log(import.meta.env.VITE_SOME_KEY) // 123
console.log(import.meta.env.DB_PASSWORD) // undefined

Além disto, a Vite usa dotenv-expand para expandir as variáveis fora da caixa. Para saber mais sobre a sintaxe, consulte a sua documentação.

Nota que se quisermos usar $ dentro do valor da nossa variável, temos de escapa-lo com \:

KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123

KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123

Se quisermos personalizar o prefixo das variáveis de ambiente, temos que consultar a opção envPrefix.

NOTAS DE SEGURANÇA

• Os ficheiros .env.*.local estão restritos ao local e podem conter variáveis sensíveis. Nós devemos adicionar *.local no nosso .gitignore para evitar que sejam verificados pela Git.

• Uma vez que quaisquer variáveis expostas ao nosso código-fonte de Vite terminarão no pacote do nosso cliente, as variáveis VITE_* não devem conter quaisquer informação sensíveis.

Sensor Inteligente para TypeScript

Por padrão, a Vite fornece definições de tipo para import.meta.env no vite/client.d.ts. Embora possamos definir mais variáveis de ambiente personalizadas nos ficheiros .env.[mode], talvez queiramos receber o Sensor Inteligente de TypeScript para as variáveis de ambiente definidas pelo utilizador que são prefixadas com VITE_.

Para alcançar isto, podemos criar um ficheiro env.d.ts no diretório src, depois aumentar a ImportMetaEnv da seguinte maneira:

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

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // mais variáveis de ambiente...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

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

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // mais variáveis de ambiente...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

Se o nosso código depender dos tipos os ambientes do navegador tais como DOM e WebWorker, podemos atualizar o campo lib no tsconfig.json:

{
  "lib": ["WebWorker"]
}

{
  "lib": ["WebWorker"]
}

Substituição de Ambiente de HTML

A Vite também suporta a substituição de variáveis de ambiente nos ficheiros de HTML. Quaisquer propriedades no import.meta.env pode ser usada nos ficheiros de HTML com a sintaxe especial %ENV_NAME%:

<h1>Vite is running in %MODE%</h1>
<p>Using data from %VITE_API_URL%</p>

<h1>Vite is running in %MODE%</h1>
<p>Using data from %VITE_API_URL%</p>

Se o ambiente não existir no import.meta.env, por exemplo, %NON_EXISTENT%, este será ignorado e não substituído, diferente de import.meta.env.NON_EXISTENT na JavaScript onde é substituída por undefined.

Partindo do principio de que a Vite é usada por muitas abstrações, intencionalmente não é opinativa sobre substituições complexas como as condicionais. A Vite pode ser estendida usando uma extensão do terreno do utilizador existente ou uma extensão personalizada que implementa o gatilho transformIndexHtml.

Modos

Por padrão, o servidor de desenvolvimento (comando dev) executa dentro do modo de development (desenvolvimento em Português) e o comando build executa dentro do modo de production (produção em Português).

Isto significa que quando executamos vite build, esta carregará as variáveis de ambiente a partir do .env.production se existir um:

# .env.production
VITE_APP_TITLE=My App

# .env.production
VITE_APP_TITLE=My App

Na nossa aplicação, podemos desenhar o título usando import.meta.env.VITE_APP_TITLE.

Em alguns casos, talvez queiramos executar vite build com um modo diferente para desenhar um título diferente. Nós podemos sobrescrever o modo padrão usado por um comando passando a opção --mode. Por exemplo, se quisermos construir a nossa aplicação para um modo de encenação:

vite build --mode staging

vite build --mode staging

E críamos um ficheiro .env.staging:

# .env.staging
VITE_APP_TITLE=My App (staging)

# .env.staging
VITE_APP_TITLE=My App (staging)

Como o vite build executa uma construção de produção por padrão, também podemos mudar isto e executar um ambiente de desenvolvimento usando um modo e configuração de ficheiro .env diferente:

# .env.testing
NODE_ENV=development

# .env.testing
NODE_ENV=development