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

Vite предоставляет определённые константы в специальном объекте import.meta.env. Эти константы определяются как глобальные переменные во время разработки и статически заменяются во время сборки, чтобы сделать «встряхивание дерева» (tree-shaking) более эффективным.

Пример

if (import.meta.env.DEV) {
  // Код внутри этого блока будет оптимизирован (tree-shaken) для продакшена
  console.log('Режим разработки')
}

Встроенные константы

Некоторые встроенные константы доступны во всех случаях:

• import.meta.env.MODE: {string} режим, в котором работает приложение (mode).

• import.meta.env.BASE_URL: {string} базовый URL, с которого обслуживается приложение. Это определяется с помощью параметра base.

• import.meta.env.PROD: {boolean} указывает, работает ли приложение в продакшен-режиме (работает ли dev-сервер с NODE_ENV='production' или приложение, собранное с NODE_ENV='production').

• import.meta.env.DEV: {boolean} указывает, работает ли приложение в режиме разработки (всегда противоположно import.meta.env.PROD).

• import.meta.env.SSR: {boolean} указывает, работает ли приложение в серверном режиме.

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

Vite автоматически предоставляет переменные окружения в объекте import.meta.env в виде строк.

Чтобы предотвратить случайное раскрытие переменных окружения клиенту, только переменные, начинающиеся с префикса VITE_, доступны в вашем коде, обработанном Vite. Например, для следующих переменных окружения:

.env

VITE_SOME_KEY=123
DB_PASSWORD=foobar

В вашем клиентском исходном коде только VITE_SOME_KEY будет доступна как import.meta.env.VITE_SOME_KEY, в то время как переменная DB_PASSWORD не будет доступна.

console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined

Если вы хотите настроить префикс переменных окружения, посмотрите опцию envPrefix.

Парсинг переменных окружения

Как показано выше, VITE_SOME_KEY является числом, но возвращает строку при парсинге. То же самое произойдет и с булевыми переменными окружения. Убедитесь, что вы преобразуете их в нужный тип при использовании в вашем коде.

Файлы .env

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

.env                # загружается во всех случаях
.env.local          # загружается во всех случаях, игнорируется git
.env.[mode]         # загружается только в указанном режиме
.env.[mode].local   # загружается только в указанном режиме, игнорируется git

Приоритеты загрузки переменных окружения

Файл переменных окружения для конкретного режима (например, .env.production) имеет более высокий приоритет, чем общий файл (например, .env).

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

Кроме того, переменные окружения, которые уже существуют на момент выполнения Vite, имеют наивысший приоритет и не будут перезаписаны файлами .env. Например, при выполнении VITE_SOME_KEY=123 vite build.

Файлы .env загружаются в начале работы Vite. Перезапустите сервер после внесения изменений.

Пользователям Bun

Если вы используете Bun, учтите, что Bun автоматически загружает файлы .env до запуска вашего скрипта. Эта встроенная особенность подставляет переменные окружения прямо в process.env, что может мешать работе Vite, так как он не переопределяет уже существующие значения process.env. Подробнее о возможных обходных решениях см. oven-sh/bun#5515.

Кроме того, Vite использует dotenv-expand для расширения переменных из коробки. Чтобы узнать больше о синтаксисе, ознакомьтесь с их документацией.

Обратите внимание, что если вы хотите использовать $ внутри значения вашей переменной окружения, вам нужно экранировать его с помощью \:

KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123

ЗАМЕТКИ ПО БЕЗОПАСНОСТИ

• Файлы .env.*.local являются локальными и могут содержать конфиденциальные переменные. Вам следует добавить *.local в ваш .gitignore, чтобы избежать их добавления в git.

• Поскольку любые переменные, доступные в вашем исходном коде Vite, окажутся в вашем клиентском пакете, переменные VITE_* не должны содержать конфиденциальную информацию.

Раскрытие переменных в обратном порядке

Vite поддерживает раскрытие переменных в обратном порядке. Например, .env ниже будет интерпретирован как VITE_FOO=foobar, VITE_BAR=bar.

.env

VITE_FOO=foo${VITE_BAR}
VITE_BAR=bar

Этот механизм не работает в shell-скриптах и других инструментах, таких как docker compose. Тем не менее, Vite поддерживает такое поведение, так как оно давно реализовано в dotenv-expand, а некоторые инструменты в экосистеме JavaScript используют старые версии, где оно присутствует.

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

IntelliSense для TypeScript

По умолчанию Vite предоставляет определения типов для import.meta.env в vite/client.d.ts. Хотя вы можете определить дополнительные пользовательские переменные окружения в файлах .env.[mode], вы можете захотеть получить IntelliSense TypeScript для пользовательских переменных окружения, которые начинаются с префикса VITE_.

Чтобы достичь этого, можно создать файл vite-env.d.ts в каталоге src, а затем дополнить ImportMetaEnv следующим образом:

 interface ViteTypeOptions {
  // Добавив эту строку, вы можете сделать тип ImportMetaEnv строгим,
  // чтобы запретить неизвестные ключи.
  // strictImportMetaEnv: unknown
}

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // больше переменных окружения...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

Если ваш код зависит от типов из браузерных сред, таких как DOM и WebWorker, вы можете обновить поле lib в tsconfig.json.

{
  "lib": ["WebWorker"]
}

Импорты нарушат расширение типов

Если расширение ImportMetaEnv не работает, убедитесь, что в vite-env.d.ts нет никаких операторов import. См. документацию TypeScript для получения дополнительной информации.

Замена констант в HTML

Vite также поддерживает замену констант в HTML-файлах. Любые свойства из import.meta.env могут использоваться в HTML-файлах с помощью специального синтаксиса %CONST_NAME%:

<h1>Vite работает в режиме %MODE%</h1>
<p>Используются данные из %VITE_API_URL%</p>

Если переменная окружения не существует в import.meta.env, например, %NON_EXISTENT%, она будет проигнорирована и не заменена, в отличие от import.meta.env.NON_EXISTENT в JS, где она заменяется на undefined.

Учитывая, что Vite используется многими фреймворками, он намеренно не навязывает сложные замены, такие как условные операторы. Vite можно расширить с помощью существующего пользовательского плагина или пользовательского плагина, который реализует хук transformIndexHtml.

Режимы

По умолчанию dev-сервер (команда dev) работает в режиме development, а команда build работает в режиме production.

Это означает, что при выполнении vite build будут загружены переменные окружения из .env.production, если такой файл существует:

.env.production

VITE_APP_TITLE=Мое приложение

В вашем приложении вы можете отобразить заголовок, используя import.meta.env.VITE_APP_TITLE.

В некоторых случаях вы можете захотеть выполнить vite build с другим режимом, чтобы отобразить другой заголовок. Вы можете переопределить режим по умолчанию, используемый для команды, передав флаг --mode. Например, если вы хотите собрать ваше приложение для режима предварительной проверки («staging»):

vite build --mode staging

И создайте файл .env.staging:

.env.staging

VITE_APP_TITLE=Мое приложение (staging)

Поскольку vite build по умолчанию собирает продакшен-сборку, вы также можете изменить это и собрать сборку для разработки, используя другой режим и конфигурацию файлов .env:

.env.testing

NODE_ENV=development

NODE_ENV и режимы

Важно отметить, что NODE_ENV (process.env.NODE_ENV) и режимы — это два разных понятия. Вот как различные команды влияют на NODE_ENV и режим:

Команда	NODE_ENV	Режим
vite build	"production"	"production"
vite build --mode development	"production"	"development"
NODE_ENV=development vite build	"development"	"production"
NODE_ENV=development vite build --mode development	"development"	"development"

Разные значения NODE_ENV и режима также отражаются на соответствующих свойствах import.meta.env:

Команда	import.meta.env.PROD	import.meta.env.DEV
NODE_ENV=production	true	false
NODE_ENV=development	false	true
NODE_ENV=other	false	true

Команда	import.meta.env.MODE
--mode production	"production"
--mode development	"development"
--mode staging	"staging"

NODE_ENV в .env-файлах

NODE_ENV=... можно установить в команде, а также в вашем файле .env. Если NODE_ENV указано в файле .env.[mode], режим может быть использован для управления его значением. Однако NODE_ENV и режимы остаются двумя разными понятиями.

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