Validação com Zod & env-schema

Q: Devo usar parse ou safeParse?

Use safeParse na entrada da aplicação quando quiser logs formatados antes de sair. Qualquer um é bom se um manipulador global formatar ZodError.

Q: Como testo código que importa env?

Passe um objeto de fixture para loadEnv({ DATABASE_URL: "postgres://..." }) e reinicie a configuração em cache entre os testes.

Q: Zod funciona com NestJS ConfigModule?

Sim. Valide process.env em ConfigModule.forRoot({ validate }) usando o mesmo schema Zod.

Q: Como valido campos opcionais apenas para produção?

Use .refine em NODE_ENV === "production" ou uniões discriminadas em NODE_ENV.

Q: Posso gerar .env.example a partir do Zod?

Não integrado. Mantenha .env.example manualmente ou crie um script a partir de metadados do schema que você adiciona como .describe().

Q: E quanto a segredos em mensagens de erro do Zod?

Zod não ecoa valores por padrão nas issues. Evite imprimir result.error.flatten().fieldErrors junto com dumps brutos de process.env.

Q: z.coerce.boolean() é seguro para env?

Boolean("false") é true em JavaScript. Prefira z.enum(["true","false"]).transform(v => v === "true").

Zod valida process.env no boot do Node.js para que deploys mal configurados falhem antes de aceitar tráfego. Um único schema fornece verificações em tempo de execução e tipos TypeScript sem desvios.

Receita

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

import { z } from "zod";
 
const envSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});
 
export type Env = z.infer<typeof envSchema>;
export const env = envSchema.parse(process.env);

# CI: valida o arquivo .env.example
npx tsx -e "import { envSchema } from './src/env'; envSchema.parse(require('dotenv').config({path:'.env.example'}).parsed)"

Quando usar isso:

Qualquer serviço com mais de 3 variáveis de ambiente
Verificações de paridade staging/prod em CI
Prevenção de URLs de banco de dados undefined em tempo de execução
Equipes integrando novos engenheiros que copiam .env.example

Exemplo de Trabalho

// src/env.ts
import { z } from "zod";
 
const envSchema = z
  .object({
    NODE_ENV: z.enum(["development", "test", "production"]),
    PORT: z.coerce.number().default(3000),
    DATABASE_URL: z.string().url(),
    REDIS_URL: z.string().url().optional(),
    CACHE_TTL_SECONDS: z.coerce.number().positive().default(300),
    STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
    LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
    OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url().optional(),
  })
  .refine(
    (e) => e.NODE_ENV !== "production" || e.OTEL_EXPORTER_OTLP_ENDPOINT,
    { message: "OTEL_EXPORTER_OTLP_ENDPOINT é obrigatório em produção", path: ["OTEL_EXPORTER_OTLP_ENDPOINT"] }
  );
 
export type Env = z.infer<typeof envSchema>;
 
function formatZodError(error: z.ZodError): string {
  return error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("\n");
}
 
export function loadEnv(source: NodeJS.ProcessEnv = process.env): Env {
  const result = envSchema.safeParse(source);
  if (!result.success) {
    console.error("Configuração de ambiente inválida:\n" + formatZodError(result.error));
    process.exit(1);
  }
  return result.data;
}
 
export const env = loadEnv();
 
// src/main.ts
import { env } from "./env";
import express from "express";
 
const app = express();
app.get("/health", (_req, res) => res.json({ ok: true, env: env.NODE_ENV }));
app.listen(env.PORT);

O que isso demonstra:

safeParse + process.exit(1) fornece saída de erro amigável ao operador
z.coerce.number() lida com portas de string do Kubernetes env
.refine impõe requisitos exclusivos de produção
z.infer exporta Env para tipagem de injeção de dependência

Mergulho Profundo

Como Funciona

Variáveis de ambiente são sempre strings (ou undefined); Zod faz coerção e validação
parse lança ZodError; safeParse retorna { success, data | error }
O schema é executado uma vez no carregamento do módulo ou em uma chamada explícita loadEnv()
Configuração inválida nunca atinge os manipuladores de rota ou pools de banco de dados

Padrões Comuns do Zod para Env

Padrão	Caso de Uso
`z.coerce.number()`	`PORT`, tamanhos de pool, timeouts
`z.coerce.boolean()`	Raro - prefira enum `"true"/"false"` para clareza
`.default()`	Padrões sensatos de desenvolvimento; omita na documentação de produção
`.optional()`	Integrações verdadeiramente opcionais
`.transform()`	Analisa blobs de env JSON
`.refine()`	Regras entre campos

// Blob de configuração JSON em uma variável de ambiente (use com moderação)
const featureFlagsSchema = z
  .string()
  .default("{}")
  .transform((s, ctx) => {
    try {
      return JSON.parse(s) as Record<string, boolean>;
    } catch {
      ctx.addIssue({ code: "custom", message: "FEATURE_FLAGS_JSON deve ser JSON válido" });
      return z.NEVER;
    }
  });

Alternativa env-schema

O pacote env-schema integra-se com Fastify e JSON Schema. Zod é mais comum em bases de código Express/Nest com foco em TypeScript e compõe com schemas de corpo de requisição.

Notas de TypeScript

// Passe Env para fábricas - nunca passe o process.env completo
export function createDbPool(cfg: Pick<Env, "DATABASE_URL">) {
  return new Pool({ connectionString: cfg.DATABASE_URL });
}

Armadilhas

Análise do env a cada importação de arquivo de teste - A ordem importa se env.ts sair em variáveis ausentes. Correção: loadEnv(testEnv) com um helper reset ou vi.stubEnv.
Padrões que ocultam segredos de produção ausentes - .default("changeme") em JWT_SECRET. Correção: Sem padrões em segredos; falhe se ausente em produção.
Registrando env analisado - console.log(env) vaza segredos. Correção: Registre apenas chaves ou use um serializador com redação.
Schemas enormes em um arquivo - 40 vars se tornam incontroláveis. Correção: Divida por domínio (dbEnv, authEnv) e mescle com .merge().
Ignorando a validação de CI do .env.example - O arquivo de exemplo se desvia do schema. Correção: O job de CI analisa .env.example através do schema.

Alternativas

Alternativa	Use Quando	Não Use Quando
`env-schema` + JSON Schema	Projetos nativos do Fastify	Você já padroniza em Zod na fronteira HTTP
`convict`	Configuração hierárquica com documentação	Serviços simples de 10 vars
`if (!process.env.X)` manual	Scripts de 2 vars	APIs de produção
`dotenv-safe`	Aplicação de chaves `.env` localmente	Produção (a plataforma injeta env)

FAQs

Devo usar parse ou safeParse?

Use safeParse na entrada da aplicação quando quiser logs formatados antes de sair. Qualquer um é bom se um manipulador global formatar ZodError.

Como testo código que importa env?

Passe um objeto de fixture para loadEnv({ DATABASE_URL: "postgres://..." }) e reinicie a configuração em cache entre os testes.

Zod funciona com NestJS ConfigModule?

Sim. Valide process.env em ConfigModule.forRoot({ validate }) usando o mesmo schema Zod.

Como valido campos opcionais apenas para produção?

Use .refine em NODE_ENV === "production" ou uniões discriminadas em NODE_ENV.

Posso gerar .env.example a partir do Zod?

Não integrado. Mantenha .env.example manualmente ou crie um script a partir de metadados do schema que você adiciona como .describe().

E quanto a segredos em mensagens de erro do Zod?

Zod não ecoa valores por padrão nas issues. Evite imprimir result.error.flatten().fieldErrors junto com dumps brutos de process.env.

Staging deve usar o mesmo schema que a produção?

Mesmo schema, valores diferentes. Campos opcionais podem diferir se .refine codificar regras específicas do ambiente.

Como lidar com chaves PEM multilinhas?

Codifique em Base64 no env ou use montagem de arquivo do gerenciador de segredos; Zod valida a presença e o comprimento mínimo, não o formato de novas linhas.

z.coerce.boolean() é seguro para env?

Boolean("false") é true em JavaScript. Prefira z.enum(["true","false"]).transform(v => v === "true").

Quando devo mudar para gerenciadores de segredos?

Quando as chaves rotacionam semanalmente ou a conformidade proíbe variáveis de ambiente em manifestos k8s. Zod ainda valida os valores resolvidos após a busca.

Relacionado

Noções Básicas de Configuração - visão geral do twelve-factor
dotenv vs Injeção de Plataforma - de onde vêm os valores
Gerenciadores de Segredos - busca de segredos em tempo de execução
Melhores Práticas de Configuração - padrões de equipe
Zod - noções básicas da biblioteca

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

Receita

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

import { z } from "zod";
 
const envSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});
 
export type Env = z.infer<typeof envSchema>;
export const env = envSchema.parse(process.env);

# CI: valida o arquivo .env.example
npx tsx -e "import { envSchema } from './src/env'; envSchema.parse(require('dotenv').config({path:'.env.example'}).parsed)"

Quando usar isso:

Qualquer serviço com mais de 3 variáveis de ambiente
Verificações de paridade staging/prod em CI
Prevenção de URLs de banco de dados undefined em tempo de execução
Equipes integrando novos engenheiros que copiam .env.example

Exemplo de Trabalho

// src/env.ts
import { z } from "zod";
 
const envSchema = z
  .object({
    NODE_ENV: z.enum(["development", "test", "production"]),
    PORT: z.coerce.number().default(3000),
    DATABASE_URL: z.string().url(),
    REDIS_URL: z.string().url().optional(),
    CACHE_TTL_SECONDS: z.coerce.number().positive().default(300),
    STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
    LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
    OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url().optional(),
  })
  .refine(
    (e) => e.NODE_ENV !== "production" || e.OTEL_EXPORTER_OTLP_ENDPOINT,
    { message: "OTEL_EXPORTER_OTLP_ENDPOINT é obrigatório em produção", path: ["OTEL_EXPORTER_OTLP_ENDPOINT"] }
  );
 
export type Env = z.infer<typeof envSchema>;
 
function formatZodError(error: z.ZodError): string {
  return error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("\n");
}
 
export function loadEnv(source: NodeJS.ProcessEnv = process.env): Env {
  const result = envSchema.safeParse(source);
  if (!result.success) {
    console.error("Configuração de ambiente inválida:\n" + formatZodError(result.error));
    process.exit(1);
  }
  return result.data;
}
 
export const env = loadEnv();
 
// src/main.ts
import { env } from "./env";
import express from "express";
 
const app = express();
app.get("/health", (_req, res) => res.json({ ok: true, env: env.NODE_ENV }));
app.listen(env.PORT);

O que isso demonstra:

safeParse + process.exit(1) fornece saída de erro amigável ao operador
z.coerce.number() lida com portas de string do Kubernetes env
.refine impõe requisitos exclusivos de produção
z.infer exporta Env para tipagem de injeção de dependência

Mergulho Profundo

Como Funciona

Variáveis de ambiente são sempre strings (ou undefined); Zod faz coerção e validação
parse lança ZodError; safeParse retorna { success, data | error }
O schema é executado uma vez no carregamento do módulo ou em uma chamada explícita loadEnv()
Configuração inválida nunca atinge os manipuladores de rota ou pools de banco de dados

Padrões Comuns do Zod para Env

Padrão	Caso de Uso
`z.coerce.number()`	`PORT`, tamanhos de pool, timeouts
`z.coerce.boolean()`	Raro - prefira enum `"true"/"false"` para clareza
`.default()`	Padrões sensatos de desenvolvimento; omita na documentação de produção
`.optional()`	Integrações verdadeiramente opcionais
`.transform()`	Analisa blobs de env JSON
`.refine()`	Regras entre campos

// Blob de configuração JSON em uma variável de ambiente (use com moderação)
const featureFlagsSchema = z
  .string()
  .default("{}")
  .transform((s, ctx) => {
    try {
      return JSON.parse(s) as Record<string, boolean>;
    } catch {
      ctx.addIssue({ code: "custom", message: "FEATURE_FLAGS_JSON deve ser JSON válido" });
      return z.NEVER;
    }
  });

Alternativa env-schema

O pacote env-schema integra-se com Fastify e JSON Schema. Zod é mais comum em bases de código Express/Nest com foco em TypeScript e compõe com schemas de corpo de requisição.

Notas de TypeScript

// Passe Env para fábricas - nunca passe o process.env completo
export function createDbPool(cfg: Pick<Env, "DATABASE_URL">) {
  return new Pool({ connectionString: cfg.DATABASE_URL });
}

Armadilhas

Análise do env a cada importação de arquivo de teste - A ordem importa se env.ts sair em variáveis ausentes. Correção: loadEnv(testEnv) com um helper reset ou vi.stubEnv.
Padrões que ocultam segredos de produção ausentes - .default("changeme") em JWT_SECRET. Correção: Sem padrões em segredos; falhe se ausente em produção.
Registrando env analisado - console.log(env) vaza segredos. Correção: Registre apenas chaves ou use um serializador com redação.
Schemas enormes em um arquivo - 40 vars se tornam incontroláveis. Correção: Divida por domínio (dbEnv, authEnv) e mescle com .merge().
Ignorando a validação de CI do .env.example - O arquivo de exemplo se desvia do schema. Correção: O job de CI analisa .env.example através do schema.

Alternativas

Alternativa	Use Quando	Não Use Quando
`env-schema` + JSON Schema	Projetos nativos do Fastify	Você já padroniza em Zod na fronteira HTTP
`convict`	Configuração hierárquica com documentação	Serviços simples de 10 vars
`if (!process.env.X)` manual	Scripts de 2 vars	APIs de produção
`dotenv-safe`	Aplicação de chaves `.env` localmente	Produção (a plataforma injeta env)

FAQs

Devo usar parse ou safeParse?

Use safeParse na entrada da aplicação quando quiser logs formatados antes de sair. Qualquer um é bom se um manipulador global formatar ZodError.

Como testo código que importa env?

Passe um objeto de fixture para loadEnv({ DATABASE_URL: "postgres://..." }) e reinicie a configuração em cache entre os testes.

Zod funciona com NestJS ConfigModule?

Sim. Valide process.env em ConfigModule.forRoot({ validate }) usando o mesmo schema Zod.

Como valido campos opcionais apenas para produção?

Use .refine em NODE_ENV === "production" ou uniões discriminadas em NODE_ENV.

Posso gerar .env.example a partir do Zod?

Não integrado. Mantenha .env.example manualmente ou crie um script a partir de metadados do schema que você adiciona como .describe().

E quanto a segredos em mensagens de erro do Zod?

Zod não ecoa valores por padrão nas issues. Evite imprimir result.error.flatten().fieldErrors junto com dumps brutos de process.env.

Staging deve usar o mesmo schema que a produção?

Mesmo schema, valores diferentes. Campos opcionais podem diferir se .refine codificar regras específicas do ambiente.

Como lidar com chaves PEM multilinhas?

Codifique em Base64 no env ou use montagem de arquivo do gerenciador de segredos; Zod valida a presença e o comprimento mínimo, não o formato de novas linhas.

z.coerce.boolean() é seguro para env?

Boolean("false") é true em JavaScript. Prefira z.enum(["true","false"]).transform(v => v === "true").

Quando devo mudar para gerenciadores de segredos?

Quando as chaves rotacionam semanalmente ou a conformidade proíbe variáveis de ambiente em manifestos k8s. Zod ainda valida os valores resolvidos após a busca.

Relacionado

Noções Básicas de Configuração - visão geral do twelve-factor
dotenv vs Injeção de Plataforma - de onde vêm os valores
Gerenciadores de Segredos - busca de segredos em tempo de execução
Melhores Práticas de Configuração - padrões de equipe
Zod - noções básicas da biblioteca

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

Validação com Zod & env-schema

Buscar na documentação

Validação com Zod & env-schema