env-файлы

.env-файлы в React-приложениях не импортируются напрямую, как обычные модули. Вместо этого они обрабатываются сборщиком (Webpack в Create React App, Vite в Vite-проектах) на этапе сборки, и их содержимое становится доступно через глобальную переменную process.env.

Как работают .env-файлы

Создайте файл .env в корне проекта (рядом с package.json):

REACT_APP_API_URL=https://api.example.com
REACT_APP_VERSION=1.2.0

Важно:

  • В Create React App переменные должны начинаться с REACT_APP_.
  • В Vite — с VITE_ (или VITE_SOME_VAR), а в коде доступны как import.meta.env.VITE_SOME_VAR.

Пример для CRA:

// .env
REACT_APP_API_URL=https://api.example.com

// Компонент
function App() {
  console.log(process.env.REACT_APP_API_URL); // "https://api.example.com"
  return null;
}

Пример для Vite:

# .env
VITE_API_URL=https://api.example.com

// Компонент
function App() {
  console.log(import.meta.env.VITE_API_URL); // "https://api.example.com"
  return null;
}

Почему нельзя импортировать .env как файл

Файл .env никогда не попадает в клиентский бандл. Сборщик читает его на этапе сборки, подставляет значения переменных в код (инлайнит их как строки), а сам файл игнорирует. Это сделано специально:

  • Чтобы избежать утечки чувствительных данных (хотя на клиенте всё равно видно),
  • Чтобы обеспечить статическую замену значений, что позволяет оптимизировать код.

Попытка написать import env from './.env' приведёт к ошибке — сборщик не обрабатывает .env как ресурс.

Поддерживаемые файлы окружения

Сборщики поддерживают разные файлы в зависимости от режима:

  • .env — общие значения для всех режимов,
  • .env.local — локальные переопределения (игнорируются в Git),
  • .env.development, .env.production — значения для конкретных режимов.

Приоритет: .env.local > .env.development.local > .env.development > .env.

Важные ограничения

  • Никаких секретов: всё, что попадает в process.env или import.meta.env, будет видно в браузере. Используйте .env только для публичных данных (URL API, флаги функций, версии).
  • Только строки: значения всегда интерпретируются как строки. Для чисел или булевых значений преобразуйте вручную: const timeout = Number(process.env.REACT_APP_TIMEOUT).
  • Переменные должны быть объявлены явно: динамический доступ вроде process.env[variableName] не работает — сборщик не может определить, какие переменные нужны.

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