Переопределение режима через флаг --mode

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

По умолчанию Vite использует два основных режима:

  • development — при запуске dev-сервера (vite)
  • production — при сборке (vite build)

Эти режимы определяют:

  • набор загружаемых .env файлов
  • значение import.meta.env.MODE
  • поведение некоторых внутренних оптимизаций

Ключевой момент: режим не является просто строковой меткой, он влияет на всю систему окружения проекта.

Параметр –mode и его роль

Флаг --mode позволяет переопределить стандартный режим выполнения:

vite --mode staging
vite build --mode staging
vite preview --mode staging

В этом случае вместо стандартных development или production будет использован режим staging.

Значение --mode влияет на:

  • import.meta.env.MODE
  • выбор .env файлов
  • поведение defineConfig

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

При запуске Vite режим определяется по следующему правилу:

  1. Если указан --mode, используется его значение

  2. Если не указан:

    • vite → development
    • vite build → production
    • vite preview → production

Таким образом, CLI-флаг имеет наивысший приоритет.

Влияние режима на загрузку .env файлов

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

  • .env
  • .env.local
  • .env.[mode]
  • .env.[mode].local

Если указан:

vite --mode staging

то будут загружены:

  • .env
  • .env.local
  • .env.staging
  • .env.staging.local

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

Доступ к режиму в коде

Текущий режим доступен через:

import.meta.env.MODE

Пример:

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

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

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

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

  • DEV = true, если mode === development
  • PROD = true, если mode === production

Использование mode в vite.config.js

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

import { defineConfig } from 'vite'

export default defineConfig(({ mode }) => {
  return {
    define: {
      __APP_MODE__: JSON.stringify(mode)
    }
  }
})

Если запустить:

vite --mode staging

то mode внутри конфигурации будет равен "staging".

Это позволяет:

  • подключать разные плагины
  • менять алиасы
  • изменять proxy-конфигурацию
  • управлять сборкой по окружениям

Переопределение поведения сборки через mode

Флаг --mode часто используется для создания дополнительных окружений:

Staging-сборка

vite build --mode staging

.env.staging:

VITE_API_URL=https://staging.api.example.com
VITE_DEBUG=true

Production с кастомными параметрами

vite build --mode production

или даже:

vite build --mode production-us

в случае региональных сборок.

Влияние на переменные VITE_

Важно, что только переменные с префиксом VITE_ доступны в коде:

VITE_API_URL=https://api.example.com
SECRET_KEY=12345

В код попадёт только:

import.meta.env.VITE_API_URL

даже при использовании --mode.

Взаимодействие mode и import.meta.env

import.meta.env формируется на этапе сборки и включает:

  • MODE (текущий режим)
  • DEV / PROD
  • все переменные VITE_ из соответствующих .env файлов

Пример:

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

При запуске:

vite --mode staging

результат будет зависеть от .env.staging.

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

Build

vite build --mode staging
  • используется режим staging
  • собирается production-бандл
  • подхватываются .env.staging

Preview

vite preview --mode staging
  • используется собранный билд
  • режим влияет на runtime-конфигурацию
  • .env.staging также применяется

Типичные сценарии использования –mode

Разделение окружений

  • development
  • staging
  • production
  • test

Разные API для одного кода

vite --mode development
vite --mode staging
vite --mode production

Feature flags

VITE_FEATURE_X=true

и управление через mode-файлы.

Частые ошибки при использовании mode

Ожидание загрузки неправильного .env

Если файл назван:

.env.stage

а используется:

vite --mode staging

он не будет загружен, потому что имя должно совпадать строго.

Использование переменных без VITE_ prefix

API_URL=https://example.com

в коде:

import.meta.env.API_URL // undefined

Взаимодействие с CLI и npm scripts

Типичный package.json:

{
  "scripts": {
    "dev": "vite",
    "dev:staging": "vite --mode staging",
    "build": "vite build",
    "build:staging": "vite build --mode staging"
  }
}

Такой подход позволяет централизованно управлять окружениями без изменения кода.

Итоговая логика работы режима

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

  • определяется mode (CLI → config → default)
  • загружаются соответствующие .env файлы
  • формируется import.meta.env
  • выполняется конфигурация vite.config.js
  • запускается dev/build/preview процесс

Ключевое свойство системы заключается в том, что --mode управляет не только строковым значением, но и всей цепочкой конфигурации и окружения приложения.

Оглавление