Определение собственных режимов

В Vite режим определяется значением mode, которое влияет на загрузку переменных окружения, поведение сборки и доступные конфигурационные ветки. По умолчанию используется два базовых режима: development и production, но архитектура позволяет создавать произвольные режимы для разных сценариев развертывания.

Режим передаётся через CLI и доступен внутри конфигурации:

vite --mode staging
vite build --mode production

Значение режима доступно в конфигурационном файле:

export default ({ mode }) => {
  console.log(mode);
  return {};
};

Механизм формирования режима

Режим влияет на три ключевых аспекта:

  • выбор .env файлов
  • значение import.meta.env.MODE
  • условную конфигурацию через defineConfig

Vite автоматически подхватывает файлы окружения в зависимости от режима:

.env                → базовые переменные
.env.local          → локальные переопределения
.env.development    → режим разработки
.env.production     → режим продакшена
.env.staging        → пользовательский режим

Порядок приоритета:

.env < .env.[mode] < .env.local < .env.[mode].local

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

Пользовательский режим создаётся простым указанием имени через --mode:

vite --mode staging

или

vite build --mode test

После этого Vite начинает искать соответствующие .env файлы:

.env.test
.env.test.local

Если такие файлы отсутствуют, используются только базовые .env.

Использование режима в конфигурации

Конфигурация Vite может быть функцией, принимающей объект с параметрами, включая mode:

import { defineConfig } from 'vite';

export default defineConfig(({ mode }) => {
  const isProduction = mode === 'production';
  const isStaging = mode === 'staging';

  return {
    server: {
      port: isStaging ? 8080 : 3000
    },
    build: {
      sourcemap: !isProduction
    }
  };
});

Такой подход позволяет полностью управлять конфигурацией в зависимости от среды.

import.meta.env и режим

Внутри клиентского кода режим доступен через:

console.log(import.meta.env.MODE);

Также доступны производные флаги:

import.meta.env.DEV
import.meta.env.PROD

Они вычисляются автоматически:

  • DEV = mode === 'development'
  • PROD = mode === 'production'

Важно учитывать, что пользовательские режимы (например, staging) не переводят PROD в true.

Влияние режима на переменные окружения

Только переменные с префиксом VITE_ попадают в клиентский код:

VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAG=true

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

const apiUrl = import.meta.env.VITE_API_URL;

При смене режима меняется источник загрузки этих переменных, но сам механизм экспорта остаётся одинаковым.

Условная логика конфигурации

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

export default defineConfig(({ mode }) => {
  switch (mode) {
    case 'development':
      return {
        server: {
          hmr: true
        }
      };

    case 'staging':
      return {
        server: {
          port: 4173
        }
      };

    default:
      return {
        build: {
          minify: true
        }
      };
  }
});

Такой подход позволяет полностью изолировать поведение среды.

Режим и плагины Vite

Режим влияет и на подключение плагинов:

import react from '@vitejs/plugin-react';

export default defineConfig(({ mode }) => {
  const isAnalyze = mode === 'analyze';

  return {
    plugins: [
      react(),
      isAnalyze && {
        name: 'bundle-analyzer-mock'
      }
    ].filter(Boolean)
  };
});

Таким образом, плагины могут включаться только в определённых режимах.

Режим и сборка проекта

При vite build режим по умолчанию — production. Это влияет на:

  • включение minify
  • tree-shaking
  • отключение dev-only кода
  • оптимизацию ассетов

Пример условного кода:

if (import.meta.env.DEV) {
  console.log('debug info');
}

Этот код будет удалён при production-сборке.

Использование нескольких пользовательских режимов

Распространённая практика — создание набора режимов:

development
production
staging
qa
demo

Каждый режим сопровождается собственным .env:

.env.qa
.env.demo

Пример запуска:

vite build --mode qa

Совмещение mode и NODE_ENV

Vite не использует NODE_ENV как основной источник режима, но синхронизирует его:

  • vite dev → development
  • vite build → production

При пользовательских режимах NODE_ENV остаётся production для build-процессов, если не переопределён вручную.

Доступ к режиму в плагинах

Плагины Vite получают режим через конфигурационный контекст:

export default function myPlugin() {
  return {
    name: 'my-plugin',
    config(config, { mode }) {
      if (mode === 'staging') {
        console.log('staging mode enabled');
      }
    }
  };
}

Это позволяет адаптировать поведение плагина под окружение.

Практическая структура режимов

Часто используется следующая структура:

.env
.env.development
.env.production
.env.staging
.env.staging.local

И соответствующие команды:

vite
vite build
vite build --mode staging

Каждый режим становится независимой конфигурационной сущностью, определяющей:

  • переменные окружения
  • параметры сервера
  • параметры сборки
  • подключаемые плагины
  • feature flags
Оглавление