Como Definir e Usar Variáveis de Ambiente no Node.js: Guia Prático

Colocar credenciais de banco de dados, chaves de API e segredos direto no código é receita para vazamento. Variáveis de ambiente são como aplicações em produção lidam com dados sensíveis com segurança – vamos fazer isso do jeito certo.

Por que Variáveis de Ambiente Importam

1. Hardcodar tudo no código – senha do banco em config.js, chave de API perdida em um comentário, segredos versionados no git. É assim que sistemas são invadidos. Não faça isso.
2. Variáveis de ambiente – você mantém dados sensíveis separados do código. Valores diferentes para desenvolvimento, staging e produção. Mais seguro, escalável e padrão de mercado.
3. Gerenciador de segredos – AWS Secrets Manager, HashiCorp Vault etc. A abordagem corporativa para sistemas grandes.

O Que São Variáveis de Ambiente, de Verdade

DB_PASSWORD=supersecret123
API_KEY=abc123xyz789
NODE_ENV=production

const password = process.env.DB_PASSWORD; // "supersecret123"
const apiKey = process.env.API_KEY; // "abc123xyz789"
const env = process.env.NODE_ENV; // "production"

Por Que Isso é Importante

O Problema: Configurar Tudo na Mão é Chato

export DB_HOST=localhost
export DB_PASSWORD=mypassword
export API_KEY=key123

$env:DB_HOST="localhost"
$env:DB_PASSWORD="mypassword"
$env:API_KEY="key123"

Usando Dotenv: o Jeito Simples

Passo 1: Instale o Dotenv

npm install dotenv

yarn add dotenv

Passo 2: Crie um Arquivo .env

DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=mysecurepassword
API_KEY=abc123xyz789
NODE_ENV=development
JWT_SECRET=your-jwt-secret-key
LOG_LEVEL=info

Passo 3: Carregue as Variáveis no Seu App

// app.js ou server.js – PRIMEIRA LINHA
require('dotenv').config();


// AGORA você pode usar process.env
const express = require('express');
const app = express();


const dbHost = process.env.DB_HOST;
const dbPort = process.env.DB_PORT;
const apiKey = process.env.API_KEY;


console.log(`Conectando no banco em ${dbHost}:${dbPort}`);
app.listen(3000);

Passo 4: Adicione .env ao .gitignore

# .gitignore
.env
.env.local
.env.*.local

Passo 5: Compartilhe um Template (Sem Segredos)

# .env.example – É este que vai pro repositório
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=change_me
API_KEY=change_me
NODE_ENV=development
JWT_SECRET=change_me
LOG_LEVEL=info

cp .env.example .env
# Depois edite o .env com os valores reais

Exemplo Prático: API em Express com Variáveis de Ambiente

// server.js
require('dotenv').config();


const express = require('express');
const postgres = require('pg');


const app = express();


// Lê configurações a partir das variáveis
const config = {
  db: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME
  },
  api: {
    port: process.env.PORT || 3000,
    apiKey: process.env.API_KEY,
    jwtSecret: process.env.JWT_SECRET
  },
  env: process.env.NODE_ENV || 'development'
};


// Valida variáveis obrigatórias
if (!config.api.apiKey) {
  throw new Error('A variável de ambiente API_KEY é obrigatória');
}


// Conecta no banco
const pool = new postgres.Pool(config.db);


// Rotas
app.get('/api/users', (req, res) => {
  const authHeader = req.headers.authorization;
  const token = authHeader?.split(' ');[1]


  // Verifica token usando JWT_SECRET
  if (!token) {
    return res.status(401).json({ error: 'Unauthorized' });
  }


  // Consulta o banco com o pool de conexões
  pool.query('SELECT * FROM users', (err, result) => {
    if (err) throw err;
    res.json(result.rows);
  });
});


// Sobe o servidor
const port = config.api.port;
app.listen(port, () => {
  console.log(`Servidor rodando na porta ${port} em modo ${config.env}`);
});

• Credenciais de banco vêm do .env
• Chaves de API e segredos são variáveis de ambiente
• O mesmo código roda em dev, staging e produção com .env diferentes
• Nada sensível vai parar no seu repositório git

Boas Práticas para Variáveis de Ambiente

1. Valide Variáveis Obrigatórias na Inicialização

require('dotenv').config();


const required = ['DB_HOST', 'DB_USER', 'DB_PASSWORD', 'API_KEY'];
const missing = required.filter(key => !process.env[key]);


if (missing.length > 0) {
  throw new Error(`Faltam variáveis de ambiente obrigatórias: ${missing.join(', ')}`);
}

2. Use um Objeto de Configuração

// config.js
require('dotenv').config();


module.exports = {
  database: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD
  },
  api: {
    key: process.env.API_KEY,
    jwtSecret: process.env.JWT_SECRET
  },
  app: {
    port: process.env.PORT || 3000,
    environment: process.env.NODE_ENV || 'development'
  }
};


// Uso
const config = require('./config');
console.log(config.database.host);

3. Use .env Diferentes para Cada Ambiente

.env           # padrão / desenvolvimento
.env.production # overrides para produção
.env.test      # ambiente de testes

const envFile = process.env.NODE_ENV === 'production'
  ? '.env.production'
  : '.env';

require('dotenv').config({ path: envFile });

4. Agrupe Variáveis com Prefixos

# Banco
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin


# Redis
REDIS_HOST=localhost
REDIS_PORT=6379


# Serviços externos
STRIPE_API_KEY=sk_...
SENDGRID_API_KEY=SG_...

5. Documente o Que Cada Variável Faz

# Conexão com banco PostgreSQL
DB_HOST=localhost      # Host do banco
DB_PORT=5432           # Porta do banco
DB_USER=admin          # Usuário
DB_PASSWORD=change_me  # Senha


# Configuração de APIs
API_KEY=change_me      # Chave de API de serviço externo
JWT_SECRET=change_me   # Segredo para assinar JWTs


# Aplicação
PORT=3000              # Porta do servidor Express
NODE_ENV=development   # Ambiente (development/staging/production)

Alternativas ao Dotenv em Produção

AWS Secrets Manager

HashiCorp Vault

Variáveis no CI/CD

Kubernetes Secrets

Aprendendo Node.js de Verdade

Resumo: Segredos Devem Ficar Fora do Código