Introdução: Por Que Variáveis de Ambiente Importam
Variáveis de ambiente são pares chave-valor armazenados no sistema operacional que controlam o comportamento da sua aplicação sem precisar modificar o código. Em JavaScript, especialmente em projetos Node.js, elas são essenciais para separar configurações sensíveis (chaves de API, senhas de banco de dados) do código-fonte. Isso protege seus dados e permite que o mesmo código rode em desenvolvimento, teste e produção com configurações diferentes.
Quando você inicia uma aplicação Node.js, o objeto process.env contém todas as variáveis de ambiente disponíveis. Entender como acessá-las e gerenciá-las é uma habilidade fundamental que diferencia projetos amadores de profissionais.
Acessando e Configurando Variáveis de Ambiente
Leitura Básica com process.env
O acesso mais direto é através do objeto global process.env. Observe este exemplo prático:
// src/config.js
const dbHost = process.env.DB_HOST || 'localhost';
const dbPort = process.env.DB_PORT || 5432;
const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error('API_KEY não definida. Configure a variável de ambiente.');
}
module.exports = {
database: {
host: dbHost,
port: parseInt(dbPort, 10),
},
apiKey,
};
Use este arquivo em sua aplicação para centralizar todas as configurações. Isso torna fácil identificar quais variáveis são obrigatórias e quais têm defaults sensatos.
Usando Arquivo .env com dotenv
Para desenvolvimento local, a biblioteca dotenv carrega variáveis de um arquivo .env automaticamente. Instale com npm install dotenv.
Crie um arquivo .env na raiz do projeto:
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=senha123
NODE_ENV=development
API_KEY=sk-abc123xyz
Carregue essas variáveis no início da sua aplicação (antes de qualquer outro código):
// src/index.js (primeira linha)
require('dotenv').config();
const config = require('./config');
const express = require('express');
const app = express();
app.get('/status', (req, res) => {
res.json({
environment: process.env.NODE_ENV,
database: config.database.host,
});
});
app.listen(3000, () => {
console.log('Servidor rodando em http://localhost:3000');
});
Importante: Adicione .env ao .gitignore para nunca fazer commit de dados sensíveis:
.env
.env.local
.env*.local
node_modules/
Estruturas de Configuração Avançadas
Padrão de Múltiplos Ambientes
Em projetos profissionais, você pode criar arquivos .env.development, .env.test e .env.production. Controle qual carregar conforme o ambiente:
// src/loadEnv.js
const path = require('path');
require('dotenv').config({
path: path.resolve(__dirname, `../.env.${process.env.NODE_ENV || 'development'}`),
});
require('dotenv').config({
path: path.resolve(__dirname, '../.env'),
override: false, // Não sobrescreve variáveis já definidas
});
Validação com Zod ou Joi
Validar configurações na inicialização previne bugs em produção:
// src/validateConfig.js
const z = require('zod');
const configSchema = z.object({
NODE_ENV: z.enum(['development', 'test', 'production']),
DB_HOST: z.string().min(1),
DB_PORT: z.coerce.number().int().positive(),
DB_USER: z.string().min(1),
DB_PASSWORD: z.string().min(8),
API_KEY: z.string().min(1),
JWT_SECRET: z.string().min(32),
PORT: z.coerce.number().int().positive().default('3000'),
});
const validated = configSchema.parse(process.env);
module.exports = validated;
Execute isso na inicialização. Se alguma variável estiver faltando ou inválida, a aplicação falha imediatamente com mensagens claras:
// src/index.js
require('dotenv').config();
const config = require('./validateConfig');
console.log(`✓ Configuração validada para ${config.NODE_ENV}`);
Boas Práticas em Produção
Variáveis em Plataformas de Hospedagem
Em produção, nunca use arquivos .env. Plataformas como Heroku, Vercel e AWS permitem definir variáveis diretamente no painel:
# Heroku CLI
heroku config:set DB_PASSWORD=prodPassword123
heroku config:get DB_PASSWORD
No Docker, use arquivos .env ou passe variáveis ao iniciar o container:
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
CMD ["node", "src/index.js"]
docker run -e DB_HOST=db.prod.com -e API_KEY=sk-prod123 myapp
Exemplo Completo com Express
// src/index.js
require('dotenv').config();
const config = require('./validateConfig');
const express = require('express');
const app = express();
app.use(express.json());
app.get('/api/status', (req, res) => {
res.json({
status: 'ok',
environment: config.NODE_ENV,
timestamp: new Date().toISOString(),
});
});
app.post('/api/secure', (req, res) => {
const token = req.headers.authorization?.split(' ')[1];
if (token === config.JWT_SECRET) {
return res.json({ message: 'Autenticado' });
}
res.status(401).json({ error: 'Não autorizado' });
});
const PORT = config.PORT;
app.listen(PORT, () => {
console.log(`Servidor rodando em porta ${PORT}`);
console.log(`Modo: ${config.NODE_ENV}`);
});
Conclusão
Dominar variáveis de ambiente e configuração em JavaScript é fundamental para construir aplicações profissionais. Os três pontos essenciais são: (1) use process.env e dotenv para separar dados sensíveis do código; (2) implemente validação rigorosa de configurações na inicialização para falhar rápido e claro; (3) nunca commite arquivos .env e sempre passe variáveis via painel em produção, não via arquivos. Com essas práticas, seu código fica seguro, portável e pronto para escalar.