Приоритет файлов: .env, .env.local, .env.[mode]

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

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

Основная идея заключается в том, что более специфичные файлы переопределяют значения из более общих.

Полный порядок приоритета загрузки

При запуске Vite в любом режиме (development, production или пользовательском mode) файлы обрабатываются в следующем порядке:

  1. .env
  2. .env.local
  3. .env.[mode]
  4. .env.[mode].local

Этот порядок отражает принцип «от общего к частному», где каждый последующий слой может переопределить предыдущий.

.env — базовый слой конфигурации

Файл .env является фундаментом всей системы переменных окружения.

Он используется для хранения значений, которые:

  • применимы ко всем режимам запуска;
  • не зависят от локальной среды разработчика;
  • могут быть общими для команды проекта.

Пример содержимого:

VITE_API_URL=https://api.example.com
VITE_APP_NAME=MyApp

Значения из этого файла считаются базовыми и могут быть переопределены на следующих этапах загрузки.

.env.local — локальные переопределения

Файл .env.local предназначен для машинно-специфичных настроек. Он:

  • игнорируется системой контроля версий (обычно добавляется в .gitignore);
  • используется для персональных значений разработчика;
  • имеет более высокий приоритет, чем .env.

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

VITE_API_URL=http://localhost:3000

Если в .env уже задан VITE_API_URL, значение из .env.local его заменит.

Важно учитывать, что .env.local применяется ко всем режимам, если не переопределён дальше.

.env.[mode] — режимо-специфичная конфигурация

Файлы вида .env.development, .env.production, .env.test привязываются к конкретному режиму запуска Vite.

Режим определяется параметром --mode, например:

vite --mode development
vite build --mode production

В этом случае Vite подгружает файл, соответствующий текущему режиму.

Пример .env.development:

VITE_DEBUG=true
VITE_API_URL=http://dev.api.local

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

.env.[mode].local — локальные переопределения режима

Файл .env.[mode].local является самым приоритетным в цепочке загрузки.

Он объединяет два принципа:

  • привязка к конкретному режиму;
  • локальная (машинная) конфигурация.

Пример .env.production.local:

VITE_API_URL=https://staging.api.internal

Этот файл используется для ситуаций, когда необходимо переопределить даже режимо-специфичные настройки без изменения общего окружения проекта.

Итоговая схема переопределения

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

.env
  ↓ переопределяется
.env.local
  ↓ переопределяется
.env.[mode]
  ↓ переопределяется
.env.[mode].local

Таким образом, последний найденный источник всегда имеет приоритет.

Поведение при конфликте значений

Если переменная определена в нескольких файлах, Vite применяет правило «последний загруженный выигрывает». Это означает:

  • одинаковые ключи не объединяются;
  • значения не сливаются;
  • происходит полная замена.

Пример:

.env

VITE_MODE=base

.env.production

VITE_MODE=production

Итог при --mode production:

VITE_MODE=production

Ограничения видимости переменных

Vite не передаёт в клиентский код все переменные окружения. Существует жёсткое ограничение:

  • только переменные с префиксом VITE_ доступны в import.meta.env;
  • остальные переменные доступны только на стороне Node.js в процессе сборки.

Это правило действует независимо от файла (.env, .env.local и т.д.).

Особенности обработки при старте dev-сервера

При запуске dev-сервера:

  • файлы читаются один раз при инициализации;
  • изменения в .env требуют перезапуска сервера;
  • порядок загрузки не меняется динамически.

Это важно учитывать при отладке конфигурации, так как ожидание «горячего обновления» env-файлов не соответствует реальному поведению Vite.

Поведение при сборке проекта

Во время vite build используется тот же механизм, что и в dev-режиме, но с учётом режима production по умолчанию (если не указан --mode).

Это означает:

  • .env.production применяется автоматически;
  • .env.production.local может переопределить значения для конкретной машины;
  • итоговый набор переменных фиксируется на этапе сборки и в рантайме не меняется.

Практическая модель приоритета в реальных проектах

В типичном проекте структура env-файлов выглядит следующим образом:

  • .env — общие настройки (API, название приложения)
  • .env.local — локальные dev-переопределения
  • .env.development — настройки для разработки
  • .env.production — настройки для продакшена
  • .env.production.local — локальные override для продакшена

Такое разделение позволяет изолировать:

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

Логическая модель разрешения значений

Если представить процесс в виде алгоритма, он выглядит так:

  1. Загрузить .env
  2. Применить .env.local, перезаписывая совпадающие ключи
  3. Загрузить .env.[mode], перезаписывая совпадения
  4. Применить .env.[mode].local как финальный слой

Итоговый объект формируется до запуска приложения и становится источником для всей дальнейшей работы Vite.

Оглавление