7. Переменные окружения

Vite предоставляет удобный механизм для работы с переменными окружения через файлы .env и объект import.meta.env. В отличие от Webpack с его process.env, Vite использует стандарт ES Modules.

Файлы .env

# .env               — загружается всегда
# .env.local         — загружается всегда, игнорируется git
# .env.development   — только в dev режиме (vite)
# .env.production    — только в production (vite build)
# .env.test          — только при тестировании (vitest)

# Специфичные для режима имеют приоритет над базовыми
# .env.local > .env
# .env.production.local > .env.production > .env

VITE_ префикс — обязательный!

.env

VITE_API_URL=https://api.example.com       # ✓ Доступна в браузере
VITE_APP_TITLE=My App                      # ✓ Доступна в браузере

SECRET_KEY=super-secret                     # ✗ НЕ попадёт в бандл!
DB_PASSWORD=mypassword                      # ✗ НЕ попадёт в бандл!

# Только переменные с префиксом VITE_ доступны в клиентском коде.
# Это защита от случайного слива секретов!

import.meta.env

// Доступные переменные в клиентском коде:
import.meta.env.MODE        // 'development' | 'production' | 'test'
import.meta.env.PROD        // boolean — true в production
import.meta.env.DEV         // boolean — true в development
import.meta.env.SSR         // boolean — true при SSR рендере
import.meta.env.BASE_URL    // Базовый URL (из config.base)

// Ваши переменные:
import.meta.env.VITE_API_URL    // 'https://api.example.com'
import.meta.env.VITE_APP_TITLE  // 'My App'

// Пример использования:
const API = import.meta.env.VITE_API_URL || 'http://localhost:8080'

TypeScript типы

Чтобы получить автодополнение для ваших переменных, добавьте их в vite-env.d.ts:

src/vite-env.d.ts

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string
  readonly VITE_APP_TITLE: string
  readonly VITE_FEATURE_FLAG: 'true' | 'false'
  // Добавьте все ваши переменные здесь
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

Несколько .env файлов для разных окружений

.env

VITE_APP_TITLE=My App

# .env.development
VITE_API_URL=http://localhost:8080
VITE_DEBUG=true

# .env.production
VITE_API_URL=https://api.myapp.com
VITE_DEBUG=false

# .env.staging (кастомный режим)
VITE_API_URL=https://staging-api.myapp.com

# Запуск с кастомным режимом
vite build --mode staging

Кастомный envPrefix

// vite.config.ts — изменить префикс (не VITE_)
export default defineConfig({
  envPrefix: 'APP_',  // Теперь работают APP_* переменные
  // или массив префиксов:
  envPrefix: ['VITE_', 'APP_'],
})

Важные предостережения

// ❌ Не используй string concatenation для имён переменных!
const key = 'VITE_API_URL'
const url = import.meta.env[key]  // Не работает в production!

// ✓ Всегда обращайся напрямую
const url = import.meta.env.VITE_API_URL  // Работает!

// Vite делает статическую замену при сборке:
// import.meta.env.VITE_API_URL → "https://api.example.com"
// Динамический доступ невозможен по той же причине

Ниже — интерактивный менеджер переменных окружения: редактируй .env файлы и смотри объект import.meta.env: