Variáveis de Ambiente

Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…

Variáveis de ambiente contêm a configuração e os segredos que a sua aplicação precisa no momento da compilação e em tempo de execução, como chaves de API, URLs de base de dados e sinalizadores de funcionalidades, sem nada disso existir no seu repositório. Este guia cobre onde vivem no Orbit, como o âmbito e a precedência funcionam, marcar um valor como secreto, importação e exportação em massa, e os erros que produzem uma variável que é de alguma forma sempre indefinida.

Onde Vivem

Abra o seu projeto no Orbit e clique no separador Env vars, em /orbit/<project-id>/env-vars.

A página está organizada em secções:

All environments (Todos os ambientes) no topo: variáveis de toda a projeto, disponíveis em todas as compilações.
Uma secção recolhível por ambiente (Production, Staging e quaisquer pré-visualizações) contendo as substituições desse ambiente.

Acima da lista existe uma caixa de pesquisa e um filtro Secrets only (Apenas segredos), que são a forma rápida de navegar por uma lista longa.

Como o Âmbito Funciona

Âmbito	O que afeta
All environments (Todos os ambientes, de toda a projeto)	Injetado em todas as compilações deste projeto
Environment-level override (Substituição de nível de ambiente)	Aplica-se apenas a esse ambiente, e tem precedência sobre o valor de toda a projeto com a mesma chave

O subtítulo na página declara a regra claramente: as variáveis de toda a projeto estão disponíveis em todas as compilações, e as substituições de nível de ambiente têm precedência.

Uma configuração típica é uma variável de toda a projeto DATABASE_URL apontando para uma base de dados de teste, com uma substituição de nível de produção apontando para a real. As compilações de produção recebem a base de dados real, tudo o resto recebe a de teste, e nada que adicione depois vaza acidentalmente as credenciais de produção para uma pré-visualização.

Existe também um controlo Available in (Disponível em) nas variáveis de toda a projeto, permitindo-lhe excluir tipos de ambiente particulares (production, staging, preview) de uma variável que é de outro modo de toda a projeto.

Detalhes completos sobre o âmbito por ambiente, incluindo o raciocínio de segurança, estão em Definir Variáveis de Ambiente Por Ambiente.

Uma variável de toda a projeto é injetada em compilações de pré-visualização de ramificações, e os URLs de pré-visualização são publicamente alcançáveis por qualquer pessoa com a ligação. As credenciais de base de dados de produção, chaves de pagamento ao vivo e fichas de administrador devem estar limitadas apenas à produção. Esta é a coisa individual mais consequente para acertar nesta página.

Adicionar uma Variável

Desloque-se para o formulário Add variable (Adicionar variável) na parte inferior do separador Env vars.
Introduza a KEY (Chave), por exemplo NEXT_PUBLIC_API_URL.
Introduza o value (valor).
Escolha um Scope (Âmbito): All environments (project-wide) (Todos os ambientes, de toda a projeto), ou uma substituição de ambiente específico.
Se escolheu de toda a projeto, use os botões Available in (Disponível em) para desseleccionar quaisquer tipos de ambiente que esta variável não deve alcançar.
Marque Mark as secret (Marcar como secreto) para qualquer coisa sensível.
Clique em Add (Adicionar).

O formulário diz-lhe o que está prestes a fazer antes de se comprometer: uma substituição de ambiente mostra um aviso dizendo que se aplicará apenas às compilações desse ambiente, e uma variável de toda a projeto restrita mostra quais os tipos de ambiente para os quais será injetada.

Quando as Alterações Entram em Vigor

Adicionar, editar ou eliminar uma variável não muda a implementação que está atualmente em direto. As variáveis são injetadas quando uma compilação é executada, portanto a alteração aplica-se a partir da próxima implementação em diante. Reimplemente depois de alterar qualquer coisa em que a sua aplicação dependa.

Orbit é explícito sobre isto. Abra a página de detalhes de uma implementação e, se a configuração tiver mudado desde que foi compilada, recebe um aviso Environment variables updated since this deployment (Variáveis de ambiente atualizadas desde esta implementação) dizendo-lhe que a alteração não entrará em vigor até reimplementar.

Segredos

Marque Mark as secret (Marcar como secreto) para qualquer coisa que não colaria num chat: chaves de API, palavras-passe de base de dados, fichas, chaves de assinatura.

Os valores secretos são mascarados no painel e têm um emblema secret (secreto). Os valores não secretos mostram um marcador (plain) (simples).

O valor de um segredo não pode ser lido novamente depois de ser guardado, nem por si nem por mais ninguém no painel. Pode substituí-lo (clique no ícone de edição, escreva um novo valor, guarde) mas não pode revelá-lo. Guarde a sua própria cópia num gestor de palavras-passe antes de o guardar aqui.

Orbit também rastreia há quanto tempo um valor está em vigor e mostra um emblema de idade em variáveis mais antigas, com uma sugestão indicando uma rotação. É apenas um empurrão, não uma imposição.

Editar e Eliminar

Clique no ícone de edição junto de uma variável para alterar o seu valor. Clique em Delete (Eliminar) para a remover e confirme: o diálogo avisa que as compilações que dependem dela quebrarão, que é a descrição exata do que acontece na próxima implementação.

Importação e Exportação em Massa

Dois botões no topo do separador lidam com trabalho em massa.

Import .env abre uma caixa de colar. Cole o conteúdo de um ficheiro .env, escolha um âmbito, e Orbit diz-lhe quantas variáveis detetou e quantas marca como secreto. Sinaliza chaves automaticamente com base nos seus nomes, portanto qualquer coisa contendo SECRET, TOKEN, KEY, PASSWORD e similares é marcada secreto antes da importação. Existe uma opção Overwrite existing variables with the same key (Sobrescrever variáveis existentes com a mesma chave), desativada por padrão.

Download .env produz um modelo contendo apenas os nomes de variável, sem valores. Destina-se a ser partilhado com um colega que depois preenche os seus próprios valores, não para ser usado como uma cópia de segurança.

Descarregar um modelo .env nunca inclui valores, inclusive para variáveis não secretas. Não há forma de exportar valores do Orbit. Se precisar de uma cópia de um valor, retire-a de onde originalmente o gerou.

Copiar Variáveis Entre Ambientes

O painel Copy variables between environments (Copiar variáveis entre ambientes) copia um conjunto inteiro de um âmbito para outro. Escolha um From (De) (nível de projeto ou um ambiente específico) e um To (Para), opcionalmente marque Overwrite variables that already exist in the target (Sobrescrever variáveis que já existem no destino), e clique em Preview (Pré-visualizar) para ver exatamente quantas serão adicionadas, atualizadas e omitidas antes de se comprometer.

Existe também uma página Env sync check (Verificação de sincronização de ambiente) que compara produção e staging chave a chave e relata o que existe apenas num, o que difere e o que coincide. É a ferramenta correta para "por que é que staging funciona e produção não".

Partilhar Variáveis Entre Projetos

Se vários projetos precisam da mesma credencial, use um env group (grupo de ambiente) em vez de copiá-lo em cada projeto. Vá para Orbit, depois Env groups (Grupos de ambiente), crie um grupo, adicione variáveis a ele e ligue os projetos que precisam delas.

As variáveis de grupo são injetadas no tempo de compilação, e as variáveis de nível de projeto e de nível de ambiente têm precedência sobre as variáveis de grupo. Pode ter até 20 grupos numa conta.

Notas de Estrutura

Quais as variáveis que alcançam o navegador é decidido pela sua estrutura, não pelo Orbit. Orbit injeta tudo em âmbito; a estrutura decide o que expor.

Next.js: as chaves prefixadas com NEXT_PUBLIC_ são inlined no pacote do navegador no tempo de compilação. Tudo o resto fica do lado do servidor.
Vite: as chaves prefixadas com VITE_ são expostas ao navegador. Tudo o resto é apenas tempo de compilação.
Aplicações Node.js: tudo em âmbito está em process.env durante a compilação e no tempo de execução quando Server mode (Modo servidor) está ativado.

Nunca marque um valor como secreto e depois também o prefixe com NEXT_PUBLIC_ ou VITE_. O sinalizador secreto apenas controla se o painel lhe mostra o valor; o prefixo controla se a sua estrutura o envia para o navegador de cada visitante. O prefixo vence.

Verificar O Que uma Compilação Realmente Recebeu

Cada página de detalhes de implementação lista as chaves de variável de ambiente que foram injetadas no tempo de compilação e as compara com a sua configuração atual: adicionadas, alteradas, removidas e inalteradas. As chaves Teal vieram de uma substituição específica do ambiente, as cinzentas do nível de projeto. Os valores nunca são armazenados ou mostrados, mas ao passar o cursor sobre uma chave dá-se uma impressão digital SHA-256, que é o suficiente para confirmar que dois ambientes contêm o mesmo valor sem o revelar.

Esta é a resposta definitiva a "a minha variável está realmente a alcançar a compilação". Verifique antes de alterar qualquer coisa mais.

Resolução de Problemas

A variável é indefinida no tempo de execução. Verifique se a implementação é posterior à alteração, depois verifique se o âmbito cobre este ambiente, depois verifique as regras de prefixo de estrutura acima. Nessa ordem.

Funciona em produção mas não numa pré-visualização. A variável está limitada apenas a produção, ou uma variável de toda a projeto tem preview desseleccionada sob Available in (Disponível em). Normalmente é intencional.

Funciona localmente mas não na compilação. O seu ficheiro .env local não está no repositório e não deve estar. Importe-o com Import .env e escolha o âmbito correto.

Staging está a perder tudo o que produção tem. Ative Inherit production env vars (Herdar variáveis de ambiente de produção) em Settings (Definições), sob Staging: environment variables (Staging: variáveis de ambiente), ou use Copy variables between environments (Copiar variáveis entre ambientes).