Встроенные переменные: MODE, BASE_URL, DEV, PROD, SSR

Vite предоставляет набор встроенных переменных окружения, доступных в коде приложения через import.meta.env. Эти переменные формируются на этапе сборки и разработки и позволяют управлять поведением приложения без ручной настройки сборочного процесса. Они являются частью спецификации Vite и не требуют дополнительной конфигурации для базового использования.

import.meta.env как точка доступа

Все встроенные переменные доступны через объект:

import.meta.env

Этот объект содержит как системные переменные Vite, так и пользовательские переменные окружения, начинающиеся с префикса VITE_. Однако системные переменные доступны всегда и не требуют префикса.

Важно учитывать, что значения import.meta.env инлайнются на этапе сборки, то есть заменяются статическими значениями в финальном бандле. Это делает их удобными для условной компиляции кода.

MODE

Переменная MODE определяет режим, в котором запущено приложение.

import.meta.env.MODE

Возможные значения

  • development — при запуске dev-сервера (vite)
  • production — при сборке (vite build)
  • пользовательские режимы, заданные через --mode

Пример запуска с кастомным режимом:

vite --mode staging

В этом случае:

import.meta.env.MODE === 'staging'

Использование MODE

MODE применяется для различения конфигураций без изменения кода:

if (import.meta.env.MODE === 'development') {
  console.log('Режим разработки')
}

Или более универсально:

const isDev = import.meta.env.MODE === 'development'
const isProd = import.meta.env.MODE === 'production'

BASE_URL

Переменная BASE_URL определяет базовый путь, по которому развернуто приложение.

import.meta.env.BASE_URL

Поведение

Значение формируется из настройки base в конфигурации Vite:

// vite.config.js
export default {
  base: '/app/'
}

В этом случае:

import.meta.env.BASE_URL === '/app/'

Если конфигурация не задана, используется /.

Практическое применение

Формирование ссылок на ресурсы

const logoUrl = `${import.meta.env.BASE_URL}logo.png`

Это позволяет корректно работать как в корне домена, так и при развертывании в поддиректории.

Навигация

window.location.href = import.meta.env.BASE_URL + 'dashboard'

Работа с роутерами

При использовании клиентских роутеров BASE_URL помогает синхронизировать base path:

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

DEV

Переменная DEV является булевым индикатором режима разработки.

import.meta.env.DEV

Значение

  • true — при запуске vite
  • false — при vite build

Особенности

DEV полностью заменяет необходимость проверки MODE === 'development' в большинстве случаев.

Примеры использования

Условная отладка

if (import.meta.env.DEV) {
  console.log('Debug информация')
}

Подключение dev-only модулей

if (import.meta.env.DEV) {
  import('./dev-tools.js')
}

Отключение тяжелых операций

if (!import.meta.env.DEV) {
  initAnalytics()
}

PROD

Переменная PROD — противоположность DEV, указывает на production-сборку.

import.meta.env.PROD

Значение

  • true — при vite build
  • false — в режиме разработки

Использование

Включение оптимизированной логики

if (import.meta.env.PROD) {
  enableCaching()
}

Отключение логирования

if (import.meta.env.PROD) {
  console.log = () => {}
}

Разделение конфигурации API

const apiUrl = import.meta.env.PROD
  ? 'https://api.example.com'
  : 'http://localhost:3000'

SSR

Переменная SSR указывает, выполняется ли код в режиме серверного рендеринга.

import.meta.env.SSR

Значение

  • true — при SSR-рендеринге (например, Vite SSR или frameworks на его основе)
  • false — в браузере

Особенности поведения

SSR позволяет писать универсальный код, который одинаково работает на сервере и клиенте, избегая ошибок, связанных с отсутствием браузерных API.

Примеры использования

Защита от обращения к window

if (!import.meta.env.SSR) {
  window.localStorage.setItem('key', 'value')
}

Разделение логики сервер/клиент

if (import.meta.env.SSR) {
  fetchDataFromDatabase()
} else {
  fetchDataFromApi()
}

Инициализация зависимостей

const storage = import.meta.env.SSR
  ? createMemoryStorage()
  : window.localStorage

Совместное использование переменных

Встроенные переменные часто применяются вместе для построения условной логики окружения.

Пример конфигурационного слоя

const isDev = import.meta.env.DEV
const isProd = import.meta.env.PROD
const isSSR = import.meta.env.SSR

const apiBase =
  isSSR
    ? 'http://internal-api'
    : isProd
      ? 'https://api.example.com'
      : 'http://localhost:3000'

Разделение поведения приложения

if (import.meta.env.DEV && !import.meta.env.SSR) {
  enableReactDevTools()
}

Управление логированием

const log = (...args) => {
  if (import.meta.env.DEV) {
    console.log(...args)
  }
}

Важные особенности встроенных переменных

Статическая подстановка

Все переменные import.meta.env.* заменяются во время сборки. Это означает:

  • нельзя изменять их во время выполнения
  • условные блоки могут полностью удаляться бандлером
  • оптимизация dead code elimination работает эффективно

Ограниченность набора

Встроенные переменные фиксированы:

  • MODE
  • BASE_URL
  • DEV
  • PROD
  • SSR

Любые дополнительные значения должны задаваться через .env файлы с префиксом VITE_.

Отсутствие динамичности

import.meta.env.DEV = false // не работает

Роль в архитектуре приложения

Использование встроенных переменных позволяет:

  • разделять окружения без дублирования кода
  • уменьшать ветвление логики конфигураций
  • централизовать управление поведением приложения
  • строить универсальные SSR/SPA решения
  • оптимизировать production-бандл за счёт удаления лишних веток

Эти переменные становятся базовым слоем окружения, на котором строится вся конфигурационная логика приложения в Vite.

Оглавление