0Pricing
Node.js Backend Development Bootcamp · Урок

Типобезопасная конфигурация окружения и проверка во время выполнения

Проверяйте переменные окружения и внешний ввод во время выполнения с помощью библиотек схем, выводимых в статические типы.

«Типобезопасная конфигурация окружения и проверка во время выполнения» — бесплатный урок Node.js Backend Development Bootcamp на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Node.js Backend Development Bootcamp, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Node.js Backend Development Bootcamp содержит 4 уроков всего.

Части этого урока еще не переведены и отображаются на английском.

Why Validate process.env?

In Node.js, every value on process.env is a string or undefined — the runtime gives you no guarantees.

  • process.env.PORT might be "3000", "", or missing entirely.
  • A typo like DATABSE_URL silently yields undefined.
  • TypeScript types process.env as Record<string, string | undefined>, so it can't catch missing keys.

Reading config ad-hoc throughout your app means crashes surface deep inside request handlers — long after startup. The fix: validate once at boot and fail fast with a clear message.

// Untyped, unsafe access scattered everywhere
const port = process.env.PORT;            // string | undefined
const dbUrl = process.env.DATABASE_URL;   // string | undefined

console.log(typeof port);  // "string" or "undefined"
console.log(Number(process.env.MISSING)); // NaN — silent failure

Schema Libraries and Type Inference

A schema library lets you describe the shape and constraints of data once, then validate at runtime AND infer a static TypeScript type from the same definition.

  • Popular choices: Zod, Valibot, ArkType, TypeBox.
  • One source of truth — the schema — produces both the runtime check and the compile-time type.
  • No duplicated interface that can drift out of sync.

We'll use Zod, the most common in the Node.js ecosystem. z.infer<typeof schema> extracts the type the schema validates.

import { z } from "zod";

const UserSchema = z.object({
  id: z.number().int(),
  email: z.string().email(),
});

// Static type inferred from the runtime schema
type User = z.infer<typeof UserSchema>;
// type User = { id: number; email: string }

A First Env Schema

Let's describe the environment our service needs. Because process.env values are always strings, the schema must coerce numeric fields and constrain string fields.

  • z.coerce.number() turns "3000" into 3000.
  • z.enum([...]) restricts a value to a fixed set.
  • Chaining like .min() / .url() adds runtime constraints.

Define the schema in its own module (e.g. src/env.ts) so it's imported once at startup.

import { z } from "zod";

export const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});

Parsing at Startup

Call schema.parse(process.env) once, at the top of your entry file. If validation fails, Zod throws a ZodError and the process exits before serving any traffic.

  • parse() returns a fully typed, validated object.
  • Coerced and defaulted values are already applied.
  • Export the result so the rest of the app imports a typed env object instead of touching process.env directly.
import { z } from "zod";
import { EnvSchema } from "./env-schema";

export const env = EnvSchema.parse(process.env);
// env.PORT is number, env.NODE_ENV is a narrowed union

const server = createServer();
server.listen(env.PORT, () => {
  console.log(`Listening on ${env.PORT} in ${env.NODE_ENV}`);
});

safeParse for Friendly Errors

A raw ZodError stack trace is noisy. Use safeParse to get a result object you can format into a readable startup message, then exit deliberately.

  • safeParse returns { success: true, data } or { success: false, error } — it never throws.
  • error.flatten().fieldErrors groups messages per field.
  • Exit with process.exit(1) so orchestrators (Docker, PM2, k8s) see a failed boot.
import { z } from "zod";

const EnvSchema = z.object({
  PORT: z.coerce.number().int().positive(),
  DATABASE_URL: z.string().url(),
});

const parsed = EnvSchema.safeParse(process.env);
if (!parsed.success) {
  console.error("Invalid environment variables:");
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}
export const env = parsed.data;

A Standalone, Runnable Example

Here is a self-contained demonstration of the validate-then-infer pattern using a plain object instead of process.env, so an online judge can run it with no setup.

It shows coercion, a default, an enum, and a friendly error path — the same techniques you'd apply to real environment loading.

import { z } from "zod";

const Schema = z.object({
  NODE_ENV: z.enum(["development", "production"]).default("development"),
  PORT: z.coerce.number().int().positive(),
});

function loadConfig(raw) {
  const result = Schema.safeParse(raw);
  if (!result.success) {
    throw new Error(JSON.stringify(result.error.flatten().fieldErrors));
  }
  return result.data;
}

const config = loadConfig({ PORT: "8080" });
console.log(config); // { NODE_ENV: 'development', PORT: 8080 }
console.log(typeof config.PORT); // number

Loading .env Files with ESM

Locally you store config in a .env file. The library dotenv reads it into process.env. With ESM and TypeScript, load it before any module that reads config.

  • Modern Node (v20.6+) has a built-in --env-file=.env flag — no dependency needed.
  • If you use dotenv, call dotenv/config at the very top, since ESM imports are hoisted and evaluated first.
  • Never commit real secrets; commit a .env.example documenting required keys.
// Option A: built-in (Node 20.6+), no import needed
// $ node --env-file=.env dist/index.js

// Option B: dotenv — must run first
import "dotenv/config";
import { EnvSchema } from "./env-schema";

export const env = EnvSchema.parse(process.env);

Reusing the Schema for Request Input

The exact same approach validates untrusted runtime input — request bodies, query params, webhook payloads. Network data is just as untyped as process.env.

  • Define a schema per endpoint, then parse the incoming JSON.
  • On failure, respond with 400 instead of crashing.
  • The parsed result is fully typed for the rest of the handler.
import { z } from "zod";

const CreateUserBody = z.object({
  email: z.string().email(),
  age: z.coerce.number().int().min(0).optional(),
});

function handleCreateUser(rawBody, res) {
  const result = CreateUserBody.safeParse(rawBody);
  if (!result.success) {
    res.status(400).json({ errors: result.error.flatten() });
    return;
  }
  const body = result.data; // { email: string; age?: number }
  // ...persist body
}

Transforms and Derived Config

Schemas can transform values during parsing, producing config that's ready to use. This keeps conversion logic next to the validation rule.

  • .transform() maps a validated value into a new shape.
  • Comma-separated env strings become arrays; flags become booleans.
  • The inferred type reflects the transformed output, not the raw input.
import { z } from "zod";

const EnvSchema = z.object({
  // "a.com,b.com" -> ["a.com", "b.com"]
  CORS_ORIGINS: z.string()
    .transform((s) => s.split(",").map((o) => o.trim()))
    .pipe(z.array(z.string().url())),
  // "true"/"false" string -> boolean
  ENABLE_CACHE: z
    .enum(["true", "false"])
    .transform((v) => v === "true")
    .default("false"),
});

Cross-Field Rules with refine

Sometimes validity depends on relationships between fields — e.g. in production a secret must be set, but locally a default is fine. Use .refine() or .superRefine() on the object schema.

  • The check runs after individual fields parse.
  • You attach a custom message and a path so the error points at the right field.
  • This encodes business rules that a flat per-field schema cannot.
import { z } from "zod";

const EnvSchema = z
  .object({
    NODE_ENV: z.enum(["development", "production"]),
    SENTRY_DSN: z.string().url().optional(),
  })
  .refine(
    (e) => e.NODE_ENV !== "production" || !!e.SENTRY_DSN,
    { message: "SENTRY_DSN is required in production", path: ["SENTRY_DSN"] }
  );

Exporting a Typed Config Singleton

The end goal: the rest of your codebase never touches process.env. It imports a single validated, typed env object.

  • Centralizing access means TypeScript autocompletes every key and flags typos at compile time.
  • Refactoring a variable name becomes a single-file change.
  • Tests can import a schema and feed mock objects instead of mutating global state.
// src/config.ts
import "dotenv/config";
import { z } from "zod";

const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url(),
});

const parsed = EnvSchema.safeParse(process.env);
if (!parsed.success) {
  console.error("❌ Invalid env:", parsed.error.flatten().fieldErrors);
  process.exit(1);
}

export const env = Object.freeze(parsed.data);
// elsewhere: import { env } from "./config";

Quick Check

Test your understanding of the type-safe config pattern.

Recap

You learned to make configuration and external input type-safe in modern Node.js:

  • Why: process.env and network data are untyped strings; validate once and fail fast.
  • Schemas: a library like Zod gives runtime validation plus inferred static types from one definition (z.infer).
  • Env loading: coerce numbers, constrain with enums/defaults, load .env via --env-file or dotenv/config before reading.
  • safeParse: format error.flatten().fieldErrors and process.exit(1) on failure.
  • Beyond env: reuse schemas for request bodies, add .transform() for derived config and .refine() for cross-field rules.
  • Result: export one frozen, typed env singleton the whole app imports.

Часто задаваемые вопросы

Урок «Типобезопасная конфигурация окружения и проверка во время выполнения» бесплатный?

Да — полный текст урока «Типобезопасная конфигурация окружения и проверка во время выполнения» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Node.js Backend Development Bootcamp, подпишись на CoddyKit PRO. Курс Node.js Backend Development Bootcamp содержит 4 уроков всего.

Чему я научусь в уроке «Типобезопасная конфигурация окружения и проверка во время выполнения»?

Проверяйте переменные окружения и внешний ввод во время выполнения с помощью библиотек схем, выводимых в статические типы. Ты практикуешь Node.js Backend Development Bootcamp с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Node.js Backend Development Bootcamp?

Предыдущий опыт не требуется. Node.js Backend Development Bootcamp на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.

Сколько времени занимает урок «Типобезопасная конфигурация окружения и проверка во время выполнения»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Node.js Backend Development Bootcamp?

Да. Каждый урок Node.js Backend Development Bootcamp включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Миграция с CommonJS на нативные модули ES
  2. Настройка tsconfig для серверных проектов Node
  3. Типобезопасная конфигурация окружения и проверка во время выполнения
  4. Быстрая итерация с tsx, горячей перезагрузкой и картами исходного кода
← Назад к Node.js Backend Development Bootcamp