dotenv vs Injeção de Plataforma

dotenv carrega pares chave-valor de um arquivo .env para process.env no seu laptop. Plataformas de produção injetam variáveis de ambiente em tempo de execução a partir de Segredos do k8s, AWS SSM, Vault ou painéis PaaS. O caminho do código Node.js é o mesmo; apenas a origem muda.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// src/load-env.ts
import { config as dotenvConfig } from "dotenv";
 
export function bootstrapEnv() {
  if (process.env.NODE_ENV === "test") return;
  if (process.env.NODE_ENV === "production") return; // a plataforma injeta o env
  dotenvConfig(); // apenas desenvolvimento
}

# Dockerfile - NÃO COPIE .env
ENV NODE_ENV=production
# DATABASE_URL definido por k8s/ECS em tempo de execução
CMD ["node", "dist/main.js"]

Quando usar isso:

• Onboarding de desenvolvedores que precisam de URLs Postgres locais sem compartilhar credenciais de produção
• Auditoria de imagens Docker para inclusão acidental de segredos
• Projetando pipelines de CI que espelham a injeção de produção
• Migrando de .env no repositório para vault de produção

Exemplo de Trabalho

// src/load-env.ts
import { config as dotenvConfig } from "dotenv";
import { existsSync } from "node:fs";
 
export function bootstrapEnv(): void {
  const nodeEnv = process.env.NODE_ENV ?? "development";
 
  if (nodeEnv === "production") {
    // Definição de tarefa ECS, manifesto k8s ou segredos Fly definem estes
    return;
  }
 
  if (nodeEnv === "test") {
    // Arquivo de configuração do Jest/Vitest define process.env diretamente
    return;
  }
 
  const path = existsSync(".env.local") ? ".env.local" : ".env";
  const result = dotenvConfig({ path });
  if (result.error && !existsSync(".env.example")) {
    console.warn(`Nenhum ${path} encontrado; copie .env.example para .env`);
  }
}
 
// src/main.ts
import { bootstrapEnv } from "./load-env";
bootstrapEnv();
import { env } from "./env"; // Zod parse após bootstrap
import express from "express";
 
const app = express();
app.listen(env.PORT);

# trecho de deployment kubernetes
env:
  - name: DATABASE_URL
    valueFrom:
      secretKeyRef:
        name: api-secrets
        key: database-url
  - name: NODE_ENV
    value: production

O que isso demonstra:

• dotenv roda apenas em desenvolvimento; produção confia no orquestrador
• A imagem Docker não contém arquivo .env
• O mesmo schema Zod env.ts valida ambas as origens, local e de produção

Mergulho Profundo

Como Funciona

• dotenv lê .env e atribui a process.env sem sobrescrever chaves existentes (por padrão)
• Plataformas definem o env antes do node iniciar - o ponto de entrada do contêiner vê o process.env completo
• Precedência: env da plataforma > export do shell > arquivo dotenv (quando override: false)
• Gerenciadores de segredos frequentemente buscam na inicialização e definem process.env programaticamente antes do parse Zod

Matriz de Ambientes

Docker e Compose

# docker-compose.yml - apenas dev
services:
  api:
    env_file:
      - .env
    environment:
      NODE_ENV: development

• env_file no Compose é ergonomia de dev, não padrão de produção
• Compose de produção (se usado) deve usar segredos do Docker ou vault externo

Notas TypeScript

// Guarda explícita no schema para misconfigurações de produção
const envSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  DATABASE_URL: z.string().url(),
}).refine(
  (e) => e.NODE_ENV !== "production" || !e.DATABASE_URL.includes("localhost"),
  { message: "A DATABASE_URL de produção não pode apontar para localhost" }
);

Armadilhas

• Commitar .env no git - Vazamento instantâneo de credenciais. Correção: .gitignore .env; commitar .env.example apenas com placeholders.
• COPY .env no Dockerfile - Segredos em camadas da imagem para sempre. Correção: Apenas injeção em tempo de execução; escanear imagens com docker history.
• dotenv em dependências de produção - Incentiva o uso indevido em produção. Correção: devDependencies quando apenas o desenvolvimento local carrega arquivos.
• Assumir que dotenv sobrescreve a plataforma - override: true pode sobrescrever segredos do k8s em configurações híbridas. Correção: Manter o padrão override: false; pular dotenv em produção inteiramente.
• Chaves diferentes por ambiente sem schema - Staging sem STRIPE_KEY falha no momento do pagamento. Correção: Um schema Zod; CI valida o template do manifesto de cada ambiente.

Alternativas

FAQs

Relacionados

• Noções Básicas de Configuração - configuração twelve-factor
• Validação de Schema Zod & env - validar após injeção
• Gerenciadores de Segredos - padrões de busca em vault
• Noções Básicas de Docker - convenções de env de imagem
• Melhores Práticas de Configuração - política de equipe

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.