Como configurar variáveis de ambiente no VPS para uma aplicação Node.js imprimir

Configurando Variáveis de Ambiente no seu VPS para uma Aplicação Node.js

Olá! Aqui é a Sensei da GeHost 🧘‍♀️ e hoje vamos falar de um assunto que separa uma aplicação Node.js "amadora" de uma profissional: variáveis de ambiente. Se você já viu erros estranhos em produção porque uma senha de banco ficou "hardcoded" no código, ou já teve que editar arquivos direto no servidor toda vez que mudava uma configuração, este guia é pra você.

Vamos com calma, passo a passo. No final, sua aplicação vai estar mais segura e muito mais fácil de manter.

O que são variáveis de ambiente e por que usá-las?

Variáveis de ambiente são valores que ficam fora do código-fonte e são carregados pelo sistema operacional (ou pelo processo) na hora em que a aplicação roda. Elas costumam guardar informações sensíveis ou que mudam conforme o ambiente, como:

• Credenciais de banco de dados (usuário, senha, host);
• Chaves de API de serviços externos;
• A porta em que o servidor Node.js vai escutar;
• Flags que indicam se está em modo "produção" ou "desenvolvimento".

Dica da Sensei: nunca, jamais, coloque senhas ou chaves de API direto no código-fonte. Se esse código for parar num repositório Git público (ou até privado, mas mal configurado), qualquer pessoa pode ver suas credenciais.

Passo 1 — Criando o arquivo .env

A forma mais comum e didática de organizar variáveis de ambiente em projetos Node.js é usando um arquivo chamado .env, na raiz do projeto. Ele funciona junto com um pacote muito popular chamado dotenv.

1. Acesse seu VPS via terminal (SSH) e navegue até a pasta do seu projeto;
2. Instale a biblioteca com o comando:
   npm install dotenv
3. Crie o arquivo .env na raiz do projeto:
   nano .env
4. Dentro dele, adicione suas variáveis no formato CHAVE=valor, uma por linha. Exemplo:
   PORT=3000
DATABASE_URL=sua_string_de_conexao
NODE_ENV=production
5. Salve o arquivo (no nano: Ctrl+O, Enter, depois Ctrl+X para sair).

Passo 2 — Carregando as variáveis no código

No arquivo principal da sua aplicação (geralmente index.js ou server.js), adicione esta linha antes de qualquer outro código que use as variáveis:

require('dotenv').config();

A partir daí, você acessa qualquer variável através do objeto global process.env, assim:

const porta = process.env.PORT;

Passo 3 — Protegendo o arquivo .env

Esse é o passo que a maioria esquece — e é justamente o mais importante para a segurança da sua aplicação.

1. Nunca envie o .env para o Git. Crie (ou edite) um arquivo .gitignore na raiz do projeto e adicione a linha:
   .env
2. Restrinja as permissões do arquivo no servidor, para que só o dono consiga ler:
   chmod 600 .env
3. Se você trabalha em equipe, compartilhe as variáveis por um canal seguro (nunca por e-mail ou chat aberto) e mantenha um arquivo de exemplo, como .env.example, só com os nomes das chaves (sem os valores reais), para orientar quem for configurar o projeto.

Alternativa: variáveis de ambiente via gerenciador de processos

Se você usa um gerenciador de processos como o PM2 para manter sua aplicação Node.js rodando em segundo plano, também é possível declarar variáveis de ambiente diretamente no arquivo de configuração dele (o famoso ecosystem.config.js), dentro de uma seção env. Isso é útil quando você quer manter tudo centralizado no processo, sem depender do .env.

Dica da Sensei: escolha um método e seja consistente. Misturar .env com variáveis exportadas manualmente no terminal costuma gerar confusão — principalmente quando a aplicação reinicia e "esquece" um valor que só existia naquela sessão do terminal.

Passo 4 — Reiniciando a aplicação

Depois de criar ou alterar variáveis de ambiente, a aplicação precisa ser reiniciada para que as mudanças tenham efeito — variáveis de ambiente só são lidas quando o processo Node.js inicia.

• Se estiver usando PM2: pm2 restart nome-da-app
• Se estiver rodando manualmente: pare o processo (Ctrl+C) e inicie novamente com node index.js ou npm start.

Checklist final

1. Arquivo .env criado com as variáveis necessárias;
2. require('dotenv').config(); no topo do arquivo principal;
3. .env incluído no .gitignore;
4. Permissões do arquivo restritas com chmod 600;
5. Aplicação reiniciada após qualquer mudança.

Se você tiver dúvidas sobre o acesso ao seu servidor ou sobre qual é a melhor forma de configurar o ambiente para o seu plano específico, dá uma olhada no painel do cliente ou fale com o nosso suporte — eles vão te orientar certinho de acordo com o que está contratado. 💙