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

Parcel поддерживает механизм подстановки переменных окружения на этапе сборки, позволяя встраивать конфигурационные значения напрямую в HTML без дополнительного JavaScript-кода. Такой подход применяется для настройки API-адресов, флагов окружения, ключей интеграций и прочих параметров, которые должны различаться между dev и production-сборками.

Синтаксис интерполяции в HTML

В HTML-файлах Parcel использует специальный шаблонный формат:

%VARIABLE_NAME%

Любая строка, обёрнутая в символы %, рассматривается как ссылка на переменную окружения. На этапе сборки Parcel заменяет её на фактическое значение.

Пример:

<script src="%API_BASE_URL%/client.js"></script>

Если в окружении определено:

API_BASE_URL=https://cdn.example.com

результирующий HTML после сборки:

<script src="https://cdn.example.com/client.js"></script>

Источники значений переменных

Parcel получает значения из нескольких источников, объединяя их в единый слой конфигурации:

  • системные переменные окружения (process environment)
  • .env файлы в корне проекта
  • .env.local, .env.development, .env.production
  • параметры запуска сборки

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

Поддержка .env файлов

Parcel автоматически подхватывает файлы .env без необходимости подключения дополнительных библиотек.

Пример .env:

API_BASE_URL=https://api.example.com
APP_NAME=MyApplication

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

<title>%APP_NAME%</title>
<link rel="stylesheet" href="%API_BASE_URL%/styles/main.css">

Поведение при отсутствии переменной

Если переменная окружения не определена, Parcel не выполняет магического восстановления значения. Вместо этого поведение зависит от конфигурации сборки:

  • возможна подстановка пустой строки
  • либо сохранение исходного шаблона в виде %NAME%
  • либо ошибка сборки (в строгих режимах или при плагинах проверки)

Практика продакшена предполагает явное определение всех используемых переменных.

Подстановка в HTML и этапы трансформации

Подстановка переменных происходит на этапе HTML-трансформации, до финальной сборки ассетов. Внутренний пайплайн Parcel включает:

  1. Парсинг HTML
  2. Поиск токенов %...%
  3. Сопоставление с окружением
  4. Замена значений
  5. Интеграция в dependency graph

Этот процесс отличается от JavaScript-замены process.env, которая происходит в рамках бандлинга модулей.

Различие между HTML и JavaScript интерполяцией

Parcel обрабатывает переменные окружения в разных контекстах по-разному.

HTML:

<meta name="api" content="%API_BASE_URL%">

Jav * aScript:

console.log(process.env.API_BASE_URL);

В JavaScript Parcel выполняет статическую замену:

console.log("https://api.example.com");

HTML же использует строковый шаблонный механизм %VAR%, независимый от process.env.

Использование в атрибутах HTML

Подстановка работает не только в содержимом тегов, но и в атрибутах:

<img src="%CDN_URL%/images/logo.png">
<a href="%DOCS_URL%/guide.html">Документация</a>

После сборки:

<img src="https://cdn.example.com/images/logo.png">
<a href="https://docs.example.com/guide.html">Документация</a>

Интеграция с различными окружениями

Часто используется разделение конфигураций по средам:

.env.development

API_BASE_URL=http://localhost:3000

.env.production

API_BASE_URL=https://api.production.com

Parcel автоматически выбирает нужный файл в зависимости от режима сборки:

parcel build index.html --mode production

Ограничения механизма

Механизм подстановки в HTML имеет ряд технических ограничений:

  • поддерживаются только строковые значения
  • невозможны вычисления или выражения внутри %...%
  • отсутствует динамическое изменение во время выполнения
  • вложенные конструкции не поддерживаются

Пример неподдерживаемого варианта:

<!-- не работает -->
%API_%VERSION%_URL%

Безопасность и утечки данных

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

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

Взаимодействие с кешированием и CDN

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

<script src="%CDN_URL%/app.%BUILD_HASH%.js"></script>

Такая схема позволяет:

  • переключать CDN без изменения кода
  • управлять окружениями без пересборки логики
  • централизованно менять базовые URL ресурсов

Поведение при вложенных ресурсах Parcel

Parcel анализирует HTML после подстановки и продолжает строить граф зависимостей. Например:

<link rel="stylesheet" href="%STYLE_PATH%">

Если значение:

STYLE_PATH=./styles/main.css

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

Сочетание с JavaScript и шаблонами

HTML-подстановка часто используется совместно с JS-конфигурацией:

<script>
  window.__CONFIG__ = {
    apiBase: "%API_BASE_URL%"
  };
</script>

В JavaScript далее используется уже готовая конфигурация без обращения к process.env.

Частые сценарии применения

  • переключение backend API между средами
  • настройка публичных CDN путей
  • управление именами приложений
  • внедрение feature flags на уровне HTML
  • конфигурация мета-тегов и SEO параметров

Особенности работы в режиме разработки

В режиме разработки Parcel выполняет подстановку аналогично production-сборке, но с возможностью быстрого обновления значений при изменении .env файлов. При этом dev-server отслеживает изменения и пересобирает HTML без полной пересборки проекта.

Обработка ошибок и диагностика

При некорректной конфигурации переменных окружения Parcel может:

  • выводить предупреждения в консоль сборки
  • оставлять необработанные токены %VAR%
  • останавливать сборку при строгих настройках

Диагностика обычно связана с:

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

Совместимость с плагинами и трансформерами

HTML-трансформер Parcel, отвечающий за подстановку, может взаимодействовать с другими плагинами:

  • минификация HTML
  • оптимизация ссылок
  • обработка ресурсов (@parcel/transformer-html)

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

Оглавление