Типизация окружения и конфигурация
Проверяйте и типизируйте переменные окружения; предоставляйте безопасные клиентские переменные через NEXT_PUBLIC; централизуйте конфигурацию для сервера и клиента.
«Типизация окружения и конфигурация» — бесплатный урок TypeScript Academy на CoddyKit. Это урок 3 из 3. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения TypeScript Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс TypeScript Academy содержит 3 уроков всего.
Введение
Цель: централизовать проверенные переменные окружения и поддерживать синхронность типов. Вы разберёте process.env с помощью zod, экспортируете типизированный объект env и предоставите клиенту только переменные NEXT_PUBLIC_*.
- Проверка во время выполнения
- Доступность на сервере и клиенте
- Единый источник истины
Схемы и разборщик
Создайте отдельные схемы для сервера и клиента. Немедленно завершайте запуск при неверной конфигурации.
// app/lib/env.ts
import { z } from "zod"
const serverSchema = z.object({
NODE_ENV: z.enum(["development", "test", "production"]),
DATABASE_URL: z.string().url(),
API_SECRET: z.string().min(1)
})
const clientSchema = z.object({
NEXT_PUBLIC_API_BASE: z.string().url()
})
function parseEnv<T extends z.ZodTypeAny>(schema: T, source: Record<string, unknown>) {
const r = schema.safeParse(source)
if (!r.success) {
console.error(r.error.format())
throw new Error("Invalid environment variables")
}
return r.data as z.infer<T>
}
export const serverEnv = parseEnv(serverSchema, process.env)
export const clientEnv = parseEnv(clientSchema, process.env)Использование на сервере
Серверные файлы (обработчики маршрутов и серверные компоненты) могут получать секреты из serverEnv. Никогда не предоставляйте их клиенту.
// app/api/users/route.ts
import { NextResponse } from "next/server"
import { serverEnv } from "@/app/lib/env"
export async function GET() {
// Safe to read secrets on the server
const db = serverEnv.DATABASE_URL
return NextResponse.json({ ok: true, dbConfigured: Boolean(db) })
}Использование на клиенте
Клиентские компоненты импортируют только clientEnv, содержащий переменные NEXT_PUBLIC_*. Секреты никогда не отправляются в браузер.
"use client"
import { clientEnv } from "@/app/lib/env"
export default function ApiBaseNotice() {
return <small>API base: {clientEnv.NEXT_PUBLIC_API_BASE}</small>
}Контекстные объявления типов
Контекстные объявления типов улучшают DX для process.env, но не выполняют проверку во время выполнения — сохраняйте проверки zod.
// env.d.ts (optional hints; runtime validation still required)
/// <reference types="node" />
declare namespace NodeJS {
interface ProcessEnv {
NODE_ENV: "development" | "test" | "production"
DATABASE_URL?: string
API_SECRET?: string
NEXT_PUBLIC_API_BASE?: string
}
}Рекомендации
Рекомендации:
- Никогда не читайте секреты в клиентских файлах.
- Проверяйте их один раз при запуске; в средах, отличных от рабочей, быстро завершайте работу, чтобы обнаруживать проблемы.
- Спрячьте доступ к окружению за небольшим модулем для единообразия и тестов.
Проверка типизации окружения
Быстрая проверка: какой шаблон безопасен для типизации и предоставления переменных окружения?
Повторение
Повторение: разбирайте process.env с помощью zod, экспортируйте типизированные serverEnv/clientEnv и используйте NEXT_PUBLIC_* для безопасного предоставления переменных клиенту.
Часто задаваемые вопросы
Урок «Типизация окружения и конфигурация» бесплатный?
Да — полный текст урока «Типизация окружения и конфигурация» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс TypeScript Academy, подпишись на CoddyKit PRO. Курс TypeScript Academy содержит 3 уроков всего.
Чему я научусь в уроке «Типизация окружения и конфигурация»?
Проверяйте и типизируйте переменные окружения; предоставляйте безопасные клиентские переменные через NEXT_PUBLIC; централизуйте конфигурацию для сервера и клиента. Ты практикуешь TypeScript Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать TypeScript Academy?
Предыдущий опыт не требуется. TypeScript Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 3.
Сколько времени занимает урок «Типизация окружения и конфигурация»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке TypeScript Academy?
Да. Каждый урок TypeScript Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Типы обработчиков App Router; серверные и клиентские компоненты
- Получение данных и типизация действий
- Типизация окружения и конфигурация