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

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

Vite предоставляет переменные env для специального объекта import.meta.env. Некоторые встроенные переменные доступны во всех случаях:

import.meta.env.MODE: {string} режим, в котором работает приложение.
import.meta.env.BASE_URL: {string} базовый URL-адрес, с которого обслуживается приложение. Это определяется параметром конфигурации base.
import.meta.env.PROD: {boolean}, работает ли приложение в продакшене.
import.meta.env.DEV: {boolean} указывает, находится ли приложение в разработке (всегда противоположно import.meta.env.PROD)
import.meta.env.SSR: {boolean}, работает ли приложение на сервере.

Замена продакшена

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

Он также заменит эти строки, появляющиеся в строках JavaScript и шаблонах Vue. Это должно быть редким случаем, но это может быть непреднамеренно. В этом случае вы можете увидеть такие ошибки, как Missing Semicolon или Unexpected token, например, когда "process.env.NODE_ENV" преобразуется в ""development": ". Есть способы обойти это поведение:

Для строк JavaScript вы можете разбить строку пробелом нулевой ширины Unicode, например, 'import.meta\u200b.env.MODE'.
Для шаблонов Vue или другого HTML, который компилируется в строки JavaScript, вы можете использовать тег <wbr>, например, import.meta.<wbr>env.MODE.

Файлы `.env`

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

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

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

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

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

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

Загруженные переменные env также отображаются в исходном коде вашего клиента через import.meta.env в виде строк.

Чтобы предотвратить случайную утечку переменных 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

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

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

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

Если вы хотите настроить префикс переменных env, смотрите параметр envPrefix.

ЗАМЕЧАНИЯ ПО БЕЗОПАСНОСТИ

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

IntelliSense для TypeScript

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

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

typescript

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

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // more env variables...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

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

json

{
  "lib": ["WebWorker"]
}

Режимы

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

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

# .env.production
VITE_APP_TITLE=My App

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

Однако важно понимать, что режим — это более широкое понятие, чем просто разработка и производство. Типичный пример: вы можете захотеть иметь «постановочный» режим, в котором он должен иметь поведение, подобное производственному, но с немного отличными переменными env от производственного.

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

bash

vite build --mode staging

И чтобы получить желаемое поведение, нам нужен файл .env.staging:

# .env.staging
NODE_ENV=production
VITE_APP_TITLE=My App (staging)

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

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