Pular para o conteúdo

Variáveis no painel

Pelo painel você define as variáveis de ambiente do seu app sem usar a API. Há três lugares, conforme o alcance: o serviço, o projeto e o time. As mudanças valem no próximo deploy; o painel oferece um botão Redeploy para aplicar na hora.

Alcance Onde abrir Quem altera
Serviço Tela do site, seção “Variáveis de <serviço>”. Valem só para este serviço. Membro ou acima
Compartilhadas do grupo Mesma tela, seção “Compartilhadas do grupo”. Valem para todos os serviços do projeto. Membro ou acima
Projeto Aba de variáveis do projeto. Membro ou acima
Time Menu Variáveis compartilhadas. Valem para todos os projetos que você ligar a elas. Administrador ou acima

Leitores veem só os nomes; o valor aparece como “Valor oculto para o seu papel”.

  1. Abra o projeto, entre no site e vá à seção “Variáveis de <serviço>”.
  2. Clique em Nova variável.
  3. Preencha Nome e Valor.
  4. Ligue Sensível se for um segredo: fica mascarada na tela e nos logs e não pode ser lida de volta (Segredos).
  5. Salve. O painel avisa “Variável X salva. Vale no próximo deploy.” e marca com Precisa de redeploy os serviços afetados.

Na tabela, cada linha tem Editar e Apagar, e as marcas Sensível, Referência e Precisa de redeploy. Ao apagar, o painel lembra que quem a referencia passará a falhar com unresolved_reference.

No campo Valor, digite ${{ e o painel sugere o que dá para referenciar (campo com sugestão automática). Use:

  • ${{api.PRIVATE_URL}}: variável de outro serviço do projeto.
  • ${{shared.REGION}}: variável compartilhada.

Se a referência apontar para algo que não existe, o painel avisa “Referência sem destino: X. O deploy falharia com unresolved_reference.” Regras e variáveis automáticas em Variáveis e referências.

A tela de variáveis do projeto e a de Variáveis compartilhadas do time usam o mesmo editor:

  • Buscar pelo nome… e o filtro Todos os ambientes (Production, Preview, Development).
  • Adicionar variável: Nome (não muda depois), Valor (várias linhas, até 64 KiB), Ambientes (escolha ao menos um), Sensível e Comentário (opcional).
  • A coluna de origem mostra Time (gerenciada na página do time) ou Projeto.
  • No time, Projetos de liga a variável a projetos. Eles a herdam no próximo deploy, e uma variável do projeto com o mesmo nome e ambiente vence a do time.

Nomes aceitam letras, números e _, sem começar por número. Reservados: PORT, HOST, HOSTNAME, NODE_ENV, CI, HOME, PATH e nomes começando por NEBULAR_. O painel sugere outro nome, como APP_PORT. Se chegar ao limite de variáveis, apague alguma para adicionar outra.

  1. Clique em Importar .env.
  2. Cole o conteúdo ou escolha o arquivo (até 1 MB).
  3. Confira a pré-visualização: cada chave aparece como ok, sobrescreve, ignorada, repetida (vale a última) ou valor grande demais.
  4. Escolha os ambientes. Se quiser, marque Marcar todas como sensíveis e Sobrescrever existentes.
  5. Clique em Importar N variáveis. O resultado diz quantas foram criadas, atualizadas e ignoradas.

Depois de mudar variáveis, aparece o aviso “Alterações valem no próximo deploy.” com o botão Redeploy. Clique para refazer o deploy atual com os novos valores (“Redeploy iniciado com as novas variáveis.”). Sem deploy ativo, publique uma versão para aplicá-las. Apagar uma variável também só tem efeito no próximo deploy.

Variáveis que começam com NEXT_PUBLIC_, VITE_, PUBLIC_ ou EXPO_PUBLIC_ entram no código enviado ao navegador, e o valor fica visível a qualquer visitante. O painel avisa: não coloque segredos nelas.

Cada mudança de configuração do serviço, incluindo variáveis, gera uma versão em Histórico de configuração. Os valores sensíveis aparecem mascarados, e Restaurar esta versão reaplica a configuração. Veja Histórico de configuração.

Sintoma O que fazer
“Esse nome é reservado pelo Nebular.” Escolha outro nome, por exemplo APP_PORT.
“Já existe X em Production…” Edite a variável existente ou desmarque esse ambiente.
“Informe o valor (valores sensíveis precisam ser digitados de novo).” Ao editar uma variável sensível, digite o valor novamente.
O app não viu o valor novo Faça o Redeploy.
Deploy falha com unresolved_reference Crie o serviço ou a variável citada, ou corrija o nome.