Developer

Переменные окружения и режимы сборки

↑ 6.2 Сборка и инфраструктура: Vite, monorepo, CI∕CD · ← Предыдущая · → Следующая

Желательно~3 мин чтенияУровень: middle

Зачем это на собесе

Разница build-time и runtime конфигурации и то, что переменные клиента — публичны.

Объяснение

Vite читает .env-файлы по режиму:

.env                # всегда
.env.local          # всегда, не в git
.env.development    # режим development (vite dev)
.env.production     # режим production (vite build)
.env.staging        # vite build --mode staging
// доступны только переменные с префиксом VITE_ (защита от утечек серверных секретов)
const api = import.meta.env.VITE_API_URL;
import.meta.env.MODE;          // "development" | "production" | свой режим
import.meta.env.DEV / PROD / BASE_URL / SSR;
// Типизация: env.d.ts
interface ImportMetaEnv { readonly VITE_API_URL: string; readonly VITE_SENTRY_DSN?: string }

Ключевой момент: import.meta.env.* подставляется на этапе сборки (build-time). Значит, один и тот же артефакт нельзя использовать для разных окружений без пересборки. Решение — runtime-конфигурация (см. Релиз SPA: runtime config, source maps, CDN-кэш и rollback): файл config.json/window.__CONFIG__, генерируемый контейнером при старте.

Режимы сборки: --mode staging меняет набор .env и MODE; условная логика (if (import.meta.env.DEV)) удаляется из prod-бандла (dead code elimination).

ТемаПравило
СекретыНикогда в клиентских переменных: любая VITE_* попадает в бандл и видна пользователю
Публичные значенияURL API, DSN Sentry, ключи публичных сервисов, флаги
defineподстановка констант (__APP_VERSION__)
Различия окруженийURL, аналитика, флаги, уровни логов
CIпеременные передаются на этапе сборки; для runtime — при запуске контейнера
Валидацияпроверять обязательные переменные при старте (Zod)
Node-переменные в конфиге ViteloadEnv(mode, process.cwd(), "")

Quasar: build.env в quasar.config, process.env.*.

Нюансы и подводные камни

  • «Секретный» ключ в VITE_* = публичный ключ.
  • Сборка для stage и prod отдельно нарушает принцип «один артефакт» — используйте runtime-конфигурацию.
  • Опечатка в имени переменной даёт undefined без ошибки: валидируйте при старте.
  • Изменение .env требует перезапуска dev-сервера.
  • Значения — строки: приводите типы ("false" — truthy).

Практика

  1. Настройте .env.development/.env.production/.env.staging и типизацию.
  2. Добавьте валидацию переменных при старте приложения.
  3. Убедитесь, что серверных секретов нет в dist.

Вопросы с ответами

Связанные темы

Вид графа

Обратные ссылки