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

# Variáveis de ambiente e segredos

> Guarde tokens, chaves de API e strings de conexão como variáveis de ambiente na Square Cloud pelo dashboard, pela CLI ou pela API, e leia-as no seu código.

Mantenha tokens de bots, chaves de API e senhas de bancos de dados fora do seu código-fonte. Defina-os como variáveis de ambiente na aplicação, e o seu código os lê em tempo de execução como qualquer outra variável.

## Defina as variáveis

As variáveis de ambiente pertencem a uma aplicação. Elas sobrevivem a reinícios e commits, mas um novo upload cria uma nova aplicação sem elas, então defina-as de novo nela.

<Tabs>
  <Tab title="Dashboard">
    1. Abra a sua aplicação no [dashboard](https://squarecloud.app/pt-br/dashboard) e vá em **Configurações** → **Variáveis de Ambiente**.
    2. Adicione cada chave e valor, ou importe um arquivo `.env` existente.
    3. Clique em **Salvar**. O dashboard pergunta se você quer reiniciar a aplicação: reinicie para que ela receba os novos valores.

    Quando você envia uma nova aplicação pelo dashboard, também pode adicionar variáveis na tela de upload, antes do primeiro start.
  </Tab>

  <Tab title="CLI">
    Execute os comandos na pasta do seu projeto. A CLI age sobre a aplicação cujo `ID` está no seu `squarecloud.app`. Para usar outra, passe `--app <app ID>` (no `list`, passe o ID como argumento).

    ```bash theme={"system"}
    # Adiciona ou atualiza variáveis (as outras continuam como estão)
    squarecloud app env set DISCORD_TOKEN=your-token LOG_LEVEL=info

    # Envia todas as linhas de um arquivo .env local
    squarecloud app env set --from-file .env

    # Lista as variáveis atuais
    squarecloud app env list

    # Remove uma variável
    squarecloud app env remove LOG_LEVEL

    # Reinicia para aplicar as alterações
    squarecloud app restart
    ```

    O `squarecloud app env replace` troca o conjunto inteiro pelo que você passar, após uma confirmação. Todos os comandos e flags estão em [variáveis de ambiente pela CLI](/pt-br/cli-reference/environment-variables); para instalar a CLI e fazer login, veja o [início rápido da CLI](/pt-br/cli-reference/quickstart).
  </Tab>

  <Tab title="VS Code">
    Na [extensão da Square Cloud](/pt-br/vscode-extension/features), clique com o botão direito na sua aplicação na barra lateral e escolha **Variáveis de ambiente** para listar, adicionar, editar ou excluir variáveis. Depois, reinicie a aplicação para aplicar as alterações.
  </Tab>

  <Tab title="API">
    Envie as variáveis para [`POST /v2/apps/{app_id}/envs`](/pt-br/api-reference/endpoint/apps/envs/add_n_edit) com uma chave de API que tenha o escopo `envs:write`:

    ```bash theme={"system"}
    curl -X POST "https://api.squarecloud.app/v2/apps/YOUR_APP_ID/envs" \
      -H "Authorization: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"envs": {"DISCORD_TOKEN": "your-token"}}'
    ```

    O mesmo caminho também [lista](/pt-br/api-reference/endpoint/apps/envs/get) (`GET`), [substitui](/pt-br/api-reference/endpoint/apps/envs/overwrite) (`PUT`) e [remove](/pt-br/api-reference/endpoint/apps/envs/remove) (`DELETE`) variáveis. A API não reinicia a aplicação: chame o [endpoint de reinício](/pt-br/api-reference/endpoint/apps/restart) em seguida.
  </Tab>
</Tabs>

<Warning>As variáveis são carregadas quando a aplicação inicia. Depois de qualquer alteração, reinicie a aplicação; caso contrário, ela continua rodando com os valores antigos.</Warning>

## Leia as variáveis no seu código

<CodeGroup>
  ```javascript Node.js theme={"system"}
  const token = process.env.DISCORD_TOKEN;

  if (!token) {
    throw new Error("DISCORD_TOKEN is not set");
  }
  ```

  ```python Python theme={"system"}
  import os

  token = os.environ.get("DISCORD_TOKEN")

  if not token:
      raise RuntimeError("DISCORD_TOKEN is not set")
  ```
</CodeGroup>

Falhar logo quando uma variável está ausente deixa uma mensagem clara nos logs, em vez de um erro confuso mais tarde, como um token inválido.

## Variáveis que a Square Cloud define para você

A sua aplicação já inicia com estas variáveis definidas:

| Variável | Valor | Use para |
| - | - | - |
| `PORT` | `80` | Escolher a porta em que o seu servidor web escuta. |
| `HOST` | `0.0.0.0` | Escolher o endereço ao qual o seu servidor web se vincula. |
| `SQUARECLOUD_APP_ID` | O ID da sua aplicação | Identificar a aplicação em tempo de execução. |
| `NODE_ENV` | `production` | Informar às bibliotecas do Node.js que elas rodam em produção (runtimes Node.js e TypeScript). |

<Warning>Não sobrescreva `PORT` nem `HOST` em um site: a plataforma só alcança um servidor na porta 80 e no host `0.0.0.0`.</Warning>

Como o `NODE_ENV` é `production`, o `npm install` pula as `devDependencies`. Se o seu comando `START` faz o build do projeto (por exemplo, com `typescript` ou `vite`), liste essas ferramentas de build em `dependencies` no `package.json`.

## Como as variáveis chegam à sua aplicação

A Square Cloud guarda as variáveis em um arquivo `.squarecloud/.env` dentro da aplicação e as carrega com um shell toda vez que a aplicação inicia, antes de as dependências serem instaladas e de o seu comando `START` ou arquivo `MAIN` rodar. Duas consequências:

* **Nomes** devem usar letras, dígitos e underscores, e não começar com um dígito.
* **Valores** com espaços ou caracteres de shell, como `$`, `&`, `;` ou `|`, precisam estar entre aspas; caso contrário, o shell os corta ou os expande. O dashboard e o `squarecloud app env set` colocam as aspas para você. Na extensão para VS Code ou na API, envolva esse valor em aspas simples você mesmo: digite `'p@ss word$1'`, ou envie `"PASSWORD": "'p@ss word$1'"` no corpo da requisição.

Os limites são 256 variáveis por aplicação, 1.024 caracteres por nome e 4.096 caracteres por valor. Sites estáticos (HTML/CSS) não suportam variáveis de ambiente e retornam `STATIC_APP_ENV_NOT_SUPPORTED`.

## Mantenha os segredos fora do seu upload

Se o seu código carrega um arquivo `.env` por conta própria (por exemplo, com o `dotenv`), esse arquivo precisa estar no upload. Listar o `.env` no [`squarecloud.ignore`](/pt-br/getting-started/squarecloud-ignore), nesse caso, inicia a aplicação sem os segredos, e um bot falha com token inválido.

A configuração mais segura: mova cada valor do seu `.env` para as variáveis de ambiente da aplicação, como mostrado acima. Depois que elas estiverem definidas, você pode deixar o `.env` fora do upload e do seu repositório Git. O `dotenv` não sobrescreve variáveis que já existem, então o mesmo código continua funcionando na sua máquina e na Square Cloud.

<Warning>Nunca faça commit de tokens ou senhas em um repositório público. Se um deles vazar, revogue-o no provedor (por exemplo, redefina o token do bot no Discord Developer Portal) e defina o novo valor aqui.</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Arquivo de configuração" icon="gear-complex-code" href="/pt-br/getting-started/config-file">
    Defina `MAIN`, `MEMORY`, `START` e os outros campos do `squarecloud.app`.
  </Card>

  <Card title="Hospede um bot do Discord" icon="discord" href="/pt-br/tutorials/bots/discord">
    Faça deploy de um bot que lê o token de uma variável de ambiente.
  </Card>

  <Card title="Erros do bot do Discord" icon="bug" href="/pt-br/platform/troubleshooting/discord-bot-errors">
    Corrija um token inválido, intents ausentes e bots que ficam offline.
  </Card>

  <Card title="Erros de conexão com banco de dados" icon="database" href="/pt-br/platform/troubleshooting/database-connection-errors">
    Conecte com uma `DATABASE_URL` e as configurações de SSL certas.
  </Card>
</CardGroup>