Gerenciando e Validando Variáveis de Ambiente no Node.js sem Dependências Externas

Acessar variáveis de ambiente através do process.env sem a devida validação pode ocasionar erros silenciosos e falhas críticas durante a execução da aplicação. A partir do Node.js v20.6.0, é possível carregar arquivos .env de forma nativa e validar a existência e o formato dessas variáveis antes de inicializar o servidor.

JavaScript

import process from 'node:process';

/**
 * Valida a presença e o formato das variáveis de ambiente críticas
 * @param {Object} esquema - Configuração das variáveis esperadas e suas regras
 * @returns {Object} Variáveis de ambiente validadas
 */
function validarEnv(esquema) {
  const envValidadas = {};
  const erros = [];

  for (const [chave, regras] of Object.entries(esquema)) {
    const valor = process.env[chave];

    // Verifica se a variável obrigatória está ausente
    if (regras.obrigatoria && !valor) {
      erros.push(`Variável obrigatória ausente: ${chave}`);
      continue;
    }

    // Aplica valor padrão caso o parâmetro não seja informado
    const valorFinal = valor || regras.padrao;

    // Converte e valida tipos numéricos (ex: PORTA)
    if (regras.tipo === 'number') {
      const numero = Number(valorFinal);
      if (Number.isNaN(numero)) {
        erros.push(`A variável ${chave} deve ser um número válido.`);
      } else {
        envValidadas[chave] = numero;
      }
    } else {
      envValidadas[chave] = valorFinal;
    }
  }

  // Interrompe o processo se houver erros de configuração
  if (erros.length > 0) {
    console.error('❌ Erro na configuração do ambiente:\n' + erros.join('\n'));
    process.exit(1);
  }

  return envValidadas;
}

// Definição do esquema de validação
const esquemaEnv = {
  PORT: { tipo: 'number', padrao: 3000, obrigatoria: false },
  API_KEY: { tipo: 'string', obrigatoria: true },
  NODE_ENV: { tipo: 'string', padrao: 'development', obrigatoria: false }
};

// Carregamento nativo do .env (Node.js v20.6.0+ via flag `--env-file=.env`)
// Exemplo prático de execução e validação das variáveis
const config = validarEnv(esquemaEnv);

console.log('✅ Configuração carregada com sucesso:');
console.log(`Servidor rodando na porta: ${config.PORT}`);
console.log(`Modo de execução: ${config.NODE_ENV}`);

Pontos-chave

• Suporte Nativo a .env: A partir do Node.js v20.6.0, não é necessário instalar o pacote dotenv; basta executar o script usando a flag --env-file=.env no terminal (ex: node --env-file=.env app.js).
• Fail-Fast (Falha Rápida): Interromper a aplicação com process.exit(1) logo na inicialização impede que o sistema rode com configurações incompletas, evitando falhas inesperadas em produção.
• Coerção de Tipos: Todas as propriedades de process.env são retornadas originalmente como string, exigindo conversões explícitas com Number() ou Boolean() para evitar bugs de comparação.
• Validação com Schemas (Alternativa em Escala): Para projetos de grande porte, recomenda-se a adoção de bibliotecas de validação de esquemas como o Zod ou Joi integradas ao process.env.