Настройки treeshake.unknownGlobalSideEffects

В процессе tree-shaking Rollup анализирует код на уровне модулей и выражений, чтобы удалить неиспользуемые части. Однако значительная часть JavaScript-кода взаимодействует с глобальной средой: обращается к window, document, globalThis, вызывает функции с побочными эффектами, модифицирует прототипы и глобальные переменные. Такие операции сложно статически доказать как безопасные для удаления.

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

Как Rollup интерпретирует глобальные побочные эффекты

При анализе кода Rollup различает несколько типов выражений:

  • вызовы функций с известной чистотой или её отсутствием;
  • обращения к локальным переменным внутри модуля;
  • обращения к импортированным сущностям;
  • обращения к глобальной среде, поведение которой не всегда детерминировано.

Если выражение затрагивает глобальную область видимости и не удаётся точно определить его побочные эффекты, оно классифицируется как unknown global side effect.

Значение настройки

treeshake.unknownGlobalSideEffects: true

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

treeshake.unknownGlobalSideEffects: false

  • Rollup допускает удаление выражений с неопределёнными глобальными побочными эффектами;
  • повышается эффективность tree-shaking;
  • возрастает риск удаления кода, который фактически влияет на окружение.

Природа «неизвестных» глобальных эффектов

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

  • вызовы функций из внешних библиотек без анализа их реализации;
  • обращение к глобальным объектам через динамические свойства;
  • выполнение выражений, где результат зависит от runtime-условий;
  • использование паттернов вроде window[someKey]();
  • импорт модулей с побочными эффектами, не описанными явно.

Пример неопределённого глобального эффекта

someGlobalFunction();

Если someGlobalFunction не импортирована и не определена в модуле, Rollup не может гарантировать её чистоту. Такое выражение попадает в категорию неизвестных глобальных побочных эффектов.

При включённом значении true оно сохраняется:

// остаётся в бандле
someGlobalFunction();

При значении false Rollup может удалить его, если анализ покажет отсутствие влияния на экспортируемое поведение.

Влияние на tree-shaking

Tree-shaking в Rollup работает как граф зависимостей:

  • узлы графа — выражения и объявления;
  • рёбра — зависимости между ними;
  • удаление происходит при доказанной недостижимости узла.

Глобальные побочные эффекты усложняют граф, так как добавляют «непрозрачные» узлы.

При true:

  • граф расширяется за счёт всех сомнительных узлов;
  • уменьшается вероятность удаления нужного кода;
  • увеличивается стабильность поведения.

При false:

  • граф становится агрессивнее оптимизированным;
  • возможны «ложные отрицания» — удаление нужного кода;
  • повышается риск различий между dev и prod сборками.

Связь с другими настройками tree-shaking

interaction с moduleSideEffects

treeshake.moduleSideEffects определяет, имеет ли модуль побочные эффекты в целом.

  • если модуль помечен как без побочных эффектов, Rollup активно удаляет его;
  • если помечен как содержащий побочные эффекты, модуль сохраняется.

unknownGlobalSideEffects работает на более низком уровне — на уровне выражений внутри модулей.

interaction с propertyReadSideEffects

treeshake.propertyReadSideEffects влияет на чтение свойств объектов.

В комбинации:

  • propertyReadSideEffects регулирует поведение доступа к свойствам;
  • unknownGlobalSideEffects регулирует поведение глобальных вызовов и выражений.

Совместно они определяют степень «консервативности» анализа.

Сценарии, где значение true предпочтительно

  • библиотеки, взаимодействующие с DOM;
  • плагины, изменяющие глобальное окружение;
  • приложения с динамической загрузкой скриптов;
  • проекты, где важнее корректность, чем размер бандла;
  • интеграции с legacy-кодом.

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

Сценарии, где значение false допустимо

  • полностью ESM-ориентированные проекты;
  • код с строгой архитектурой без обращения к globalThis;
  • библиотеки с явной декларацией sideEffects;
  • проекты, где весь внешний код хорошо типизирован и контролируем.

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

Поведение при смешанных модулях

В реальных приложениях часто встречается комбинация:

  • ESM-модули;
  • CommonJS через плагин;
  • сторонние библиотеки без декларации side effects.

В такой среде unknownGlobalSideEffects становится фактором стабилизации, поскольку компенсирует недостаток информации о внешнем коде.

Типичные ошибки интерпретации

Ожидание полного удаления побочных выражений

Даже при агрессивных настройках Rollup не может гарантировать удаление кода, если существует шанс влияния на глобальное состояние.

Игнорирование глобальных мутаций

window.config = {};

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

Неправильная оценка внешних библиотек

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

Практическая модель принятия решений внутри Rollup

При обработке выражения алгоритм упрощённо действует так:

  1. Определение локальности выражения;
  2. Проверка импортов и экспортов;
  3. Анализ вызовов функций;
  4. Попытка определения побочных эффектов;
  5. Если результат неопределён — применяется unknownGlobalSideEffects.

Итоговое влияние на архитектуру сборки

Параметр формирует баланс между:

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

В сложных приложениях этот параметр становится страховочным механизмом, ограничивающим риск некорректного tree-shaking на уровне глобального контекста исполнения.

Оглавление