Переменные окружения: файлы .env и .env.local

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

В экосистеме Parcel поддерживается автоматическая загрузка переменных из файлов окружения. Значения становятся доступны в коде через объект process.env.

Наиболее распространённые сценарии использования:

  • адреса API-серверов;
  • идентификаторы аналитических систем;
  • флаги включения и отключения функциональности;
  • параметры сборки;
  • настройки для различных окружений (разработка, тестирование, продакшен).

Пример:

API_URL=https://api.example.com
APP_NAME=MyApplication
ENABLE_DEBUG=true

Использование в Jav * aScript:

console.log(process.env.API_URL);
console.log(process.env.APP_NAME);

Во время сборки Parcel подставляет соответствующие значения вместо обращений к переменным окружения.

Файлы окружения в Parcel

Parcel поддерживает несколько типов файлов конфигурации окружения.

Наиболее часто используются:

.env
.env.local

Также доступны специализированные варианты:

.env.development
.env.production
.env.test

.env.development.local
.env.production.local
.env.test.local

Каждый файл предназначен для определённого сценария использования.

Файл .env

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

Пример структуры:

APP_NAME=Shop
API_URL=https://api.shop.com
LOG_LEVEL=info

Структура проекта:

project/
├── src/
├── package.json
├── .env
└── .parcelrc

После запуска Parcel автоматически считывает содержимое файла и делает значения доступными во время сборки.

Использование:

const apiUrl = process.env.API_URL;

fetch(`${apiUrl}/products`)
    .then(response => response.json())
    .then(data => console.log(data));

Синтаксис объявления переменных

Каждая переменная описывается в формате:

KEY=value

Примеры:

PORT=3000
DEBUG=true
MAX_CONNECTIONS=100

Строковые значения:

APP_TITLE=Online Store

Значения с пробелами рекомендуется заключать в кавычки:

APP_TITLE="Online Store"

Поддерживаются одинарные кавычки:

APP_TITLE='Online Store'

Комментарии в файлах окружения

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

Пример:

# URL основного сервера
API_URL=https://api.example.com

# Включение режима отладки
DEBUG=true

Parcel игнорирует строки, начинающиеся с символа #.

Переменные нескольких окружений

Разработка и продакшен обычно используют разные настройки.

Например:

.env.development

API_URL=http://localhost:3000
DEBUG=true

.env.production

API_URL=https://api.company.com
DEBUG=false

Код приложения остаётся неизменным:

console.log(process.env.API_URL);

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

Файл .env.local

Файл .env.local предназначен для локальных настроек конкретного разработчика.

Обычно в нём размещаются:

  • секретные ключи;
  • локальные адреса сервисов;
  • персональные настройки;
  • временные параметры отладки.

Пример:

API_URL=http://localhost:8080
TOKEN=my-secret-token

Такой файл не должен попадать в систему контроля версий.

Типичная запись в .gitignore:

.env.local

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

Приоритет .env.local

Одной из важнейших особенностей является переопределение значений.

Допустим, существует файл .env:

API_URL=https://api.production.com

И файл .env.local:

API_URL=http://localhost:3000

При сборке Parcel выберет значение из .env.local:

console.log(process.env.API_URL);

Результат:

http://localhost:3000

Локальные настройки обладают более высоким приоритетом.

Типичная схема использования .env и .env.local

Основной файл:

APP_NAME=CRM
API_URL=https://api.company.com

Локальный файл:

API_URL=http://localhost:5000

Код:

const config = {
    appName: process.env.APP_NAME,
    apiUrl: process.env.API_URL
};

console.log(config);

Результат:

{
    appName: "CRM",
    apiUrl: "http://localhost:5000"
}

Общие настройки берутся из .env, а индивидуальные переопределяются через .env.local.

Подстановка переменных внутри других переменных

Parcel поддерживает расширение переменных.

Пример:

HOST=localhost
PORT=3000

API_URL=http://${HOST}:${PORT}

Использование:

console.log(process.env.API_URL);

Результат:

http://localhost:3000

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

Использование значений в HTML

Переменные окружения могут применяться не только в JavaScript.

Пример HTML-файла:

<meta name="api-url" content="${API_URL}">

Файл окружения:

API_URL=https://api.example.com

После обработки Parcel значение будет автоматически подставлено.

Результат:

<meta name="api-url" content="https://api.example.com">

Использование в конфигурационных файлах

Часто параметры окружения используются при создании конфигурационных объектов.

Пример:

export const config = {
    apiUrl: process.env.API_URL,
    analyticsId: process.env.ANALYTICS_ID,
    debug: process.env.DEBUG === "true"
};

Файл окружения:

API_URL=https://api.example.com
ANALYTICS_ID=GA-12345
DEBUG=true

Использование:

import { config } from "./config";

if (config.debug) {
    console.log("Debug mode enabled");
}

Значения по умолчанию

Иногда переменная может отсутствовать.

Для предотвращения ошибок используются значения по умолчанию.

Пример:

const apiUrl =
    process.env.API_URL || "http://localhost:3000";

Или через оператор объединения с null:

const apiUrl =
    process.env.API_URL ?? "http://localhost:3000";

Такой код остаётся работоспособным даже при отсутствии переменной.

Проверка обязательных переменных

Для критически важных параметров полезно выполнять проверку.

Пример:

if (!process.env.API_URL) {
    throw new Error("API_URL is not defined");
}

Более масштабный вариант:

const required = [
    "API_URL",
    "AUTH_URL",
    "CLIENT_ID"
];

required.forEach(name => {
    if (!process.env[name]) {
        throw new Error(`${name} is required`);
    }
});

Это позволяет обнаружить ошибки конфигурации ещё на этапе запуска приложения.

Безопасность и секретные данные

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

Если значение используется в браузерном коде:

console.log(process.env.API_KEY);

Parcel встроит его в итоговую сборку.

Следовательно, любой пользователь сможет увидеть значение через инструменты разработчика или исходные файлы бандла.

Поэтому в клиентских проектах нельзя хранить:

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

Подобные данные должны находиться исключительно на серверной стороне.

Организация файлов в реальном проекте

Типичная структура:

project/
├── src/
├── public/
├── .env
├── .env.local
├── .env.development
├── .env.production
├── .gitignore
└── package.json

Содержимое файлов:

.env

APP_NAME=My App
API_URL=https://api.example.com

.env.development

DEBUG=true

.env.production

DEBUG=false

.env.local

API_URL=http://localhost:3000

Такое разделение делает конфигурацию понятной и удобной для сопровождения.

Рекомендуемая стратегия хранения настроек

Для крупных проектов часто используется следующая схема:

.env

Общие значения, одинаковые для всех разработчиков.

APP_NAME=Dashboard

.env.local

Персональные настройки рабочего окружения.

API_URL=http://localhost:8080

.env.production

Параметры продакшен-сервера.

API_URL=https://api.company.com

.env.development

Параметры локальной разработки.

API_URL=http://dev-api.company.local
DEBUG=true

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

Оглавление