Como configurar variáveis de ambiente (.env) em uma aplicação Node.js hospedada no VPS

Como configurar variáveis de ambiente (.env) numa aplicação Node.js no seu servidor

Oi! Aqui é a Sensei da GeHost 🥋 Se você tem uma aplicação Node.js rodando no seu ambiente e precisa guardar informações sensíveis — como chave de API, senha de banco de dados, token de serviço externo — sem deixar isso "duro" (hardcoded) dentro do código, este guia é pra você. Vamos usar um arquivo .env, que é o jeito padrão e seguro de fazer isso no mundo Node.js.

Se você não sabe se o seu plano tem acesso via SSH/terminal ou apenas painel de arquivos, dá uma conferida no painel.gehost.com.br ou fale com o nosso suporte antes de começar — assim você já sabe qual caminho seguir abaixo.

Por que usar um arquivo .env?

Imagina que sua aplicação precisa se conectar a um banco de dados ou a uma API externa. Colocar a senha direto no código-fonte é arriscado: qualquer pessoa que veja o código (ou se ele vazar num repositório público) tem acesso a essa senha. O arquivo .env resolve isso guardando essas informações fora do código, num arquivo separado que fica só no servidor.

Passo 1 — Acesse os arquivos da sua aplicação

Você tem duas formas comuns de chegar até os arquivos da sua aplicação:

• Via terminal (SSH): se seu ambiente permite acesso via SSH, conecte-se normalmente e navegue até a pasta onde está a aplicação Node.js.
• Via Gerenciador de Arquivos do cPanel: entre no painel, acesse a ferramenta Gerenciador de Arquivos e localize a pasta da sua aplicação.

Passo 2 — Crie o arquivo .env

1. Na raiz da pasta da sua aplicação (o mesmo nível onde fica o package.json), crie um novo arquivo chamado exatamente .env (com o ponto na frente e sem extensão).
2. Pelo Gerenciador de Arquivos: clique em + Arquivo, digite .env como nome e confirme. Alguns painéis escondem arquivos que começam com ponto — se não aparecer, ative a opção de "mostrar arquivos ocultos" nas configurações do Gerenciador de Arquivos.
3. Pelo terminal, um comando simples como criar o arquivo com um editor de texto (ex.: nano .env) já resolve.

Passo 3 — Preencha as variáveis

Dentro do .env, cada linha é uma variável no formato NOME=valor, sem espaços ao redor do = e sem aspas (a menos que o valor realmente precise delas). Por exemplo:

DB_HOST=localhost
DB_USER=meu_usuario
DB_PASSWORD=minhasenha123
API_KEY=abc123xyz
PORT=3000

Dica da Sensei: nunca coloque espaço antes ou depois do =, e evite comentar dados sensíveis em texto puro em outros lugares do projeto. O .env é o único lugar onde eles devem morar.

Passo 4 — Instale o pacote que lê o .env

A maioria das aplicações Node.js usa o pacote dotenv para carregar essas variáveis automaticamente. No terminal, dentro da pasta do projeto, rode:

npm install dotenv

E logo no início do arquivo principal da sua aplicação (geralmente index.js, app.js ou server.js), adicione:

require('dotenv').config();

A partir daí, qualquer variável do .env fica disponível no seu código através de process.env. Por exemplo:

console.log(process.env.DB_USER);

Passo 5 — Proteja o arquivo .env

Esse é um passo que muita gente esquece e que é essencial:

• Se o seu projeto usa Git, adicione a linha .env no arquivo .gitignore para que ele nunca seja enviado a um repositório (mesmo que privado).
• Não compartilhe o conteúdo do .env por e-mail, chat ou print de tela.
• Se precisar repassar credenciais para alguém da sua equipe, prefira um canal seguro combinado internamente, e não o próprio arquivo exposto.

Passo 6 — Reinicie a aplicação

Depois de criar ou alterar o .env, a aplicação precisa ser reiniciada para carregar os novos valores — simplesmente editar o arquivo não atualiza uma aplicação que já está rodando. Reinicie o processo Node.js da forma como ele normalmente é gerenciado no seu ambiente (por exemplo, via gerenciador de processos como PM2, ou reiniciando o serviço configurado para sua aplicação).

Dica da Sensei: se depois de reiniciar as variáveis ainda não aparecerem certas no process.env, confira se não sobrou nenhum espaço extra, se o arquivo está mesmo na raiz do projeto e se o require('dotenv').config() está numa das primeiras linhas do arquivo principal — antes de qualquer código que use essas variáveis.

Ficou com dúvida?

Se algo não sair como esperado, ou se você não tiver certeza do tipo de acesso que seu ambiente permite (terminal ou apenas painel), nosso suporte está por aqui pra te ajudar — é só abrir um chamado pelo painel.gehost.com.br. Bora deixar sua aplicação rodando redondinha! 🚀