> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ambarks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variáveis de ambiente

> Configure secrets e parâmetros usados pela aplicação.

# <Icon icon="code" color="#0516ee" size={30} /> Variáveis de ambiente

Variáveis de ambiente servem para configurar sua aplicação sem colocar dados sensíveis no código. Use para URLs, tokens, credenciais, flags e configurações por ambiente.

## Criar variável

1. Abra o projeto no dashboard.
2. Acesse a área de variáveis.
3. Clique para adicionar uma nova variável.
4. Informe chave e valor.
5. Marque como secret quando o valor for sensível.
6. Salve e faça um novo deploy para aplicar.

## Limites e validações

* Você pode salvar até **100 variáveis** por projeto por requisição em lote.
* Chaves aceitam apenas letras/números/underscore (regex): `^[A-Z0-9_]+$` (case-insensitive).

## Campos

| Campo     | Descrição                                                  |
| --------- | ---------------------------------------------------------- |
| Chave     | Nome da variável, como `DATABASE_URL`                      |
| Valor     | Conteúdo usado pela aplicação                              |
| Secret    | Mascara o valor no dashboard                               |
| Build arg | Disponibiliza a variável durante o build quando necessário |

## Variáveis reservadas (evite sobrescrever)

Algumas variáveis são usadas com frequência pela plataforma e/ou por runtimes. Evite criar variáveis com o mesmo nome **com valores incompatíveis**:

| Variável           | Observação                                                                         |
| ------------------ | ---------------------------------------------------------------------------------- |
| `PORT`             | Deve bater com a porta interna do projeto; muitos exemplos usam `process.env.PORT` |
| `NODE_ENV`         | Comum em Node.js (`production`, `development`)                                     |
| `PYTHONUNBUFFERED` | Útil para logs em tempo real em Python                                             |

Se você não tiver certeza se um nome é reservado no seu plano/ambiente, prefira nomes com prefixo do seu app (ex.: `MYAPP_...`).

## Boas práticas

* Use nomes em caixa alta, como `DATABASE_URL`, `APP_ENV` e `API_KEY`.
* Não envie secrets dentro do repositório ou ZIP.
* Faça novo deploy após alterar variáveis usadas pela aplicação.
* Use valores diferentes para teste e produção.

## Exemplos comuns

| Variável       | Exemplo                  |
| -------------- | ------------------------ |
| `PORT`         | `3000`                   |
| `NODE_ENV`     | `production`             |
| `DATABASE_URL` | URL de conexão com banco |
| `APP_URL`      | URL pública da aplicação |

## Problemas comuns

| Sintoma                          | O que verificar                                            |
| -------------------------------- | ---------------------------------------------------------- |
| App não reconhece a variável     | Confirme se houve novo deploy                              |
| Valor aparece mascarado          | Variável marcada como secret                               |
| Build falha por variável ausente | Marque como build arg quando ela for usada durante o build |

## Links relacionados

* [Deploy via GitHub](/projetos/deploy-github)
* [Deploy via ZIP](/projetos/deploy-zip)
* [Logs e métricas](/projetos/logs-metricas)