Типизация переменных окружения
Задайте для process.env точный тип с проверкой
«Типизация переменных окружения» — бесплатный урок TypeScript Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения TypeScript Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс TypeScript Academy содержит 4 уроков всего.
Проблема с process.env
В Node.js тип process.env задан как Record<string, string | undefined>. Любая переменная может отсутствовать, а все значения являются строками, поэтому прямой доступ небезопасен и не типизирован.
Объявление типизированного интерфейса окружения
Начните с точного описания конфигурации, которая действительно нужна приложению, указав правильные типы и различая обязательные и необязательные поля.
interface Env {
PORT: number;
NODE_ENV: "development" | "production";
DATABASE_URL: string;
DEBUG?: boolean; // optional
}Чтение исходных значений
Все значения поступают как строки или undefined. Читать их нужно осторожно, поскольку соответствующие ключи могут просто отсутствовать.
const rawPort = process.env.PORT; // string | undefined
const rawEnv = process.env.NODE_ENV; // string | undefinedОбязательные и необязательные переменные
Некоторые переменные необходимы для работы приложения, а для других предусмотрены разумные резервные значения. Вспомогательная функция для обязательных значений немедленно сообщает об ошибке, если значение отсутствует.
function required(name: string): string {
const v = process.env[name];
if (v === undefined) throw new Error("Missing env: " + name);
return v;
}Разбор чисел
Числовые переменные необходимо преобразовывать и проверять, поскольку parseInt может вернуть NaN. Оберните разбор так, чтобы неверные входные данные отклонялись сразу.
function num(name: string): number {
const n = Number(required(name));
if (Number.isNaN(n)) throw new Error(name + " is not a number");
return n;
}Разбор логических значений
Логические значения поступают как строки, например "true". Явно нормализуйте их, а не полагайтесь на истинность непустой строки.
function bool(name: string, def = false): boolean {
const v = process.env[name];
if (v === undefined) return def;
return v === "true" || v === "1";
}Создание типизированной конфигурации
Соберите разобранные значения в один объект, соответствующий интерфейсу Env. С этого момента остальная часть приложения использует типизированную конфигурацию и никогда не обращается напрямую к process.env.
const env: Env = {
PORT: num("PORT"),
NODE_ENV: required("NODE_ENV") as Env["NODE_ENV"],
DATABASE_URL: required("DATABASE_URL"),
DEBUG: bool("DEBUG"),
};Ограничение строковых объединений
Для переменных с фиксированным набором значений проверяйте принадлежность этому набору, чтобы неожиданное значение не прошло как литеральный тип другого вида.
function oneOf<T extends string>(name: string, allowed: readonly T[]): T {
const v = required(name) as T;
if (!allowed.includes(v)) throw new Error(name + " invalid");
return v;
}Централизация доступа
Экспортируйте один объект env из единственного модуля. Каждый потребитель импортирует его, получая полную типизацию и единое место для изменения логики разбора.
export const config = env;
// elsewhere: import { config } from "./config";Расширение ProcessEnv (необязательно)
Вы можете объявить расширение модуля для NodeJS.ProcessEnv, чтобы типизировать прямой доступ, но разобранный объект конфигурации безопаснее, поскольку он также выполняет проверку и преобразование.
// declare global { namespace NodeJS { interface ProcessEnv { PORT: string } } }Почему типизированный объект конфигурации лучше
Разобранная и проверенная конфигурация обеспечивает правильные типы (числа, логические значения, объединения), гарантированное наличие обязательных переменных и один импорт для всего приложения вместо разбросанных небезопасных обращений к process.env.
Быстрая проверка
Краткая проверка по этому уроку.
Итоги
Объявите типизированный интерфейс Env, а затем разберите process.env с помощью вспомогательных функций, которые преобразуют и проверяют значения (числа, логические значения, объединения строк) и сообщают об ошибке при отсутствии обязательных переменных. Экспортируйте один типизированный объект config, чтобы приложение никогда не обращалось к исходному process.env.
Изучай TypeScript с ИИ-репетитором — бесплатно
Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.
- Курсы
- 101
- Уроки
- 352
Часто задаваемые вопросы
Урок «Типизация переменных окружения» бесплатный?
Да — полный текст урока «Типизация переменных окружения» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс TypeScript Academy, подпишись на CoddyKit PRO. Курс TypeScript Academy содержит 4 уроков всего.
Чему я научусь в уроке «Типизация переменных окружения»?
Задайте для process.env точный тип с проверкой Ты практикуешь TypeScript Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать TypeScript Academy?
Предыдущий опыт не требуется. TypeScript Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.
Сколько времени занимает урок «Типизация переменных окружения»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке TypeScript Academy?
Да. Каждый урок TypeScript Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Типизация переменных окружения
- Конфигурация с проверкой по схеме
- Слои конфигурации и значения по умолчанию
- Секреты и типобезопасность