Хук augmentChunkHash

В процессе генерации бандла Rollup формирует выходные чанки и рассчитывает для каждого из них хеш, который используется в именах файлов, кэшировании и интеграции с CDN. Хук augmentChunkHash позволяет вмешаться в финальную стадию вычисления этого хеша и добавить собственный вклад в его значение.

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

Сигнатура и время вызова

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

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

augmentChunkHash(chunkInfo)

chunkInfo содержит метаданные чанка, включая:

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

Возвращаемое значение — строка, которая добавляется к исходному хешу чанка. Если возвращается undefined или пустое значение, хеш остаётся без изменений.

Принцип работы хеширования чанка

Механизм формирования итогового хеша можно представить как последовательность шагов:

  1. Rollup формирует граф модулей и разбивает его на чанки.
  2. Для каждого чанка генерируется финальный код.
  3. Вычисляется базовый хеш содержимого.
  4. Вызываются плагины с augmentChunkHash.
  5. Возвращённые строки объединяются с базовым хешем.
  6. Формируется финальное имя файла.

Важно, что augmentChunkHash не влияет на содержимое чанка. Он влияет исключительно на идентификатор, используемый для кэширования.

Когда используется augmentChunkHash

Этот хук применяется в сценариях, где необходимо управлять стабильностью или инвалидировать кэш без изменения исходного кода:

1. Инвалидация кэша по внешним данным

Если сборка зависит от внешних параметров, не входящих в граф зависимостей (например, переменные окружения, время сборки, версия API), можно добавить их в хеш:

export default function buildMetaPlugin() {
  return {
    name: 'build-meta',
    augmentChunkHash(chunkInfo) {
      return process.env.API_VERSION || '';
    }
  };
}

Изменение версии API приведёт к изменению имени выходного файла.

2. Контроль кэширования CDN

В системах с агрессивным CDN-кэшированием важно, чтобы любые значимые изменения приводили к новому URL файла. Иногда содержимое не меняется, но меняется контекст исполнения:

  • feature flags
  • региональные настройки
  • сборочные профили

В таких случаях augmentChunkHash используется как дополнительный источник стабильности хеша.

3. Привязка к версии сборщика или плагина

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

Влияние на кэш и производительность

Добавление данных в хеш напрямую влияет на систему кэширования:

  • изменённый хеш → новый файл
  • неизменённый хеш → повторное использование кеша

Это делает хук мощным инструментом, но требует аккуратности. Любое избыточное изменение строки приводит к деградации эффективности кэша.

Особенно важно учитывать:

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

Отличие от renderChunk

Частая путаница возникает между augmentChunkHash и renderChunk.

renderChunk:

  • изменяет содержимое чанка
  • влияет на итоговый код
  • может изменять импорт/экспорт

augmentChunkHash:

  • не трогает код
  • влияет только на идентификатор чанка
  • используется после генерации кода

Иными словами, первый управляет содержимым, второй — метаданными кэширования.

Детерминизм и важные ограничения

Хук должен быть строго детерминированным. Rollup ожидает, что при одинаковом входе он всегда вернёт одинаковый результат. Нарушение этого правила приводит к нестабильным сборкам:

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

Пример неправильного подхода:

augmentChunkHash() {
  return Date.now().toString(); // недетерминированно
}

Правильный подход — только стабильные данные:

augmentChunkHash() {
  return this.meta.version;
}

Работа с chunkInfo

Объект chunkInfo предоставляет контекст, который можно использовать для построения хеша:

  • имя чанка
  • список модулей
  • экспортируемые символы
  • динамические зависимости

Это позволяет делать хеш более точным, например, учитывать только определённые типы модулей:

augmentChunkHash(chunkInfo) {
  const hasCSS = chunkInfo.modules.some(m => m.id.endsWith('.css'));
  return hasCSS ? 'css-bound' : '';
}

Влияние на code splitting

При использовании сложных стратегий code splitting хеш чанка становится критическим элементом стабильности. augmentChunkHash может быть использован для:

  • разделения окружений (prod/dev)
  • разделения регионов
  • разделения функциональных флагов

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

Типичные ошибки при использовании

Часто встречаются следующие проблемы:

Нестабильные источники данных Любые значения, которые могут изменяться между сборками, ломают кэш.

Избыточное включение информации Добавление лишних параметров приводит к постоянной смене хеша без реальной причины.

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

Позиция в архитектуре плагинов

augmentChunkHash относится к позднему этапу пайплайна сборки. Его роль можно описать как финальную корректировку идентификатора, когда вся основная работа уже завершена.

Он находится между:

  • генерацией кода чанка
  • финальной записью файлов на диск

и фактически завершает процесс формирования стабильного артефакта сборки.

Оглавление