Исключение зависимостей через optimizeDeps.exclude

В режиме разработки Vite выполняет предварительное преобразование зависимостей через esbuild, объединяя множество мелких ESM-модулей в более крупные чанки. Этот процесс ускоряет последующую загрузку приложения и снижает количество HTTP-запросов. Поведение управляется системой dependency pre-bundling, которая активируется автоматически при старте dev-сервера.

В ряде случаев требуется исключить отдельные пакеты из этого процесса. Для этого используется параметр optimizeDeps.exclude.

Назначение optimizeDeps.exclude

Параметр optimizeDeps.exclude позволяет явно указать зависимости, которые не должны попадать в предварительную оптимизацию.

Основная идея заключается в том, что Vite не будет:

  • анализировать импорт указанного пакета через esbuild
  • включать его в pre-bundling-кэш
  • преобразовывать его в оптимизированный ESM-бандл
// vite.config.js
export default {
  optimizeDeps: {
    exclude: ['some-package']
  }
}

Поведение Vite при исключении зависимости

Исключённая зависимость обрабатывается иначе:

  • импорт остаётся «сырым» и обрабатывается на лету через dev-сервер
  • браузеру может отдаваться исходный ESM или преобразованный модуль без объединения
  • увеличивается количество отдельных модулей, которые загружаются по сети
  • отсутствует кэш предварительно собранного пакета в node_modules/.vite

Такой режим отключает ключевую оптимизацию Vite, поэтому используется только при необходимости.

Сценарии применения optimizeDeps.exclude

1. Некорректная работа с esbuild

Некоторые библиотеки содержат конструкции, которые esbuild не может корректно обработать в рамках pre-bundling:

  • динамические require
  • нестандартные экспорты
  • смешение ESM и CommonJS без явных полей module/exports

В таких случаях исключение из оптимизации предотвращает ошибки трансформации.

2. Конфликты с ESM-экспортами

Отдельные пакеты предоставляют несколько форматов сборки, но определяются в package.json некорректно. Это может приводить к:

  • выбору неподходящей сборки Vite
  • дублированию зависимостей
  • ошибкам импорта типа Named export not found

Исключение позволяет отдать контроль загрузки самому dev-серверу.

3. Проблемы с side effects

Если пакет содержит побочные эффекты при импорте, pre-bundling может изменить порядок выполнения кода. В таких случаях исключение сохраняет оригинальную структуру модулей.

4. Диагностика проблемных зависимостей

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

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

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

Использование exclude напрямую влияет на поведение dev-сервера.

Положительные эффекты:

  • устранение ошибок сборки зависимостей
  • стабильная работа проблемных библиотек

Отрицательные эффекты:

  • увеличение количества модулей, загружаемых браузером
  • рост времени холодного старта dev-сервера
  • ухудшение кеширования pre-bundling слоя
  • увеличение нагрузки на HTTP-контекст модулей

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

Взаимодействие с optimizeDeps.include

exclude работает совместно с include, и между ними существует приоритетная логика:

  • include явно добавляет зависимость в pre-bundling
  • exclude запрещает оптимизацию, даже если пакет импортируется косвенно
export default {
  optimizeDeps: {
    include: ['some-package'],
    exclude: ['some-package']
  }
}

В конфликтной ситуации exclude имеет более высокий приоритет.

Кэширование и сброс оптимизации

Vite сохраняет результат оптимизации в директории:

node_modules/.vite

При добавлении зависимости в exclude происходит:

  • игнорирование ранее созданного кэша
  • возможная необходимость очистки .vite директории
  • пересборка графа зависимостей при следующем запуске dev-сервера

Изменение конфигурации exclude часто требует перезапуска сервера разработки, поскольку dependency graph строится на старте.

Особенности работы с CommonJS пакетами

Некоторые CommonJS-библиотеки могут некорректно оптимизироваться esbuild. При исключении:

  • Vite отдаёт управление трансформацией модулей runtime-слою
  • CJS → ESM интероп выполняется динамически
  • сохраняется оригинальная структура require

Это может быть полезно для библиотек, активно использующих module.exports и динамическую загрузку.

Монорепозитории и workspace-зависимости

В монорепозиториях (pnpm, yarn workspaces) часто встречаются локальные пакеты, которые:

  • не имеют стандартного dist-сборщика
  • экспортируют исходные ESM-файлы
  • зависят от alias-структуры

Исключение таких зависимостей из оптимизации позволяет избежать:

  • преждевременного объединения модулей
  • нарушения workspace-резолвинга
  • конфликтов с alias-путями

Ошибки, связанные с неправильным использованием exclude

1. Ухудшение cold start

Чрезмерное исключение зависимостей приводит к росту числа модулей, обрабатываемых браузером напрямую, что замедляет старт dev-сервера.

2. Дублирование загрузок

Без pre-bundling один и тот же пакет может загружаться в виде множества мелких модулей.

3. Нестабильность HMR

Hot Module Replacement становится менее предсказуемым из-за отсутствия единого оптимизированного графа зависимостей.

Диагностика и анализ поведения

Для анализа влияния exclude используется встроенная диагностика Vite:

  • логирование оптимизации зависимостей при запуске dev-сервера
  • просмотр списка включённых и исключённых пакетов
  • анализ кеша .vite/deps

Поведение можно косвенно оценивать по:

  • времени старта сервера
  • количеству запросов в network tab
  • структуре загруженных ESM-модулей

Сравнение с полным отключением optimizeDeps

Полное отключение:

optimizeDeps: {
  disabled: true
}

и частичное исключение через exclude отличаются принципиально:

  • disabled: true отключает весь механизм pre-bundling
  • exclude сохраняет оптимизацию для остальных зависимостей

exclude используется как точечная корректировка, тогда как disabled — радикальная мера.

Типичные проблемные библиотеки

В практике чаще всего требуют исключения:

  • библиотеки с нестандартной ESM/CJS упаковкой
  • старые пакеты без корректного module поля
  • модули с динамическим импортом через строковые переменные
  • плагины, рассчитанные на bundler-agnostic среду

Поведение всегда зависит от конкретной структуры пакета и способа его публикации.

Роль exclude в архитектуре Vite

optimizeDeps.exclude является инструментом управления границей между:

  • предварительно собранным dependency graph
  • runtime-обработкой модулей в dev-сервере

Он позволяет переключать отдельные зависимости из режима «bundled pre-cache» в режим «live ESM resolution», сохраняя гибкость системы загрузки без полного отключения оптимизации.

Оглавление