Parcel активно использует многоуровневое кэширование, чтобы ускорять
сборку и сокращать время пересборки проекта. Основная идея заключается в
сохранении промежуточных результатов трансформаций модулей и повторном
их использовании при следующих запусках сборщика.
Ключевые элементы системы кэширования:
- Файловый кэш на диске
(
.parcel-cache)
- Инкрементальная сборка
- Кэширование трансформаций (transform cache)
- Кэширование зависимостей графа модулей
- Хеширование выходных файлов для продакшена
В идеальном сценарии это обеспечивает почти мгновенные пересборки.
Однако при неправильной конфигурации или изменении окружения кэш
становится источником трудноуловимых ошибок.
Структура кэша Parcel
В современных версиях Parcel (v2+) кэш хранится в директории:
.parcel-cache/
Внутри содержатся:
- данные о графе зависимостей
- результаты трансформаций (Babel, TypeScript, PostCSS и т.д.)
- метаданные о файлах
- служебные индексы для быстрого поиска изменений
Parcel не требует ручного управления этим каталогом в нормальных
условиях, но его поведение критично при диагностике проблем.
Основные классы проблем с
кэшем
Устаревшие результаты
трансформации
Одна из наиболее частых проблем — Parcel продолжает использовать
старую версию результата трансформации файла.
Причины:
- изменения в конфигурации Babel / TypeScript не были учтены
- обновление плагинов без очистки кэша
- изменение версии Node.js
- конфликт зависимостей в
node_modules
Проявление:
- код изменён, но в браузере отображается старая логика
- HMR не отражает изменения
- сборка проходит успешно, но результат некорректен
Несогласованность графа
зависимостей
Parcel строит граф модулей и кэширует его структуру. При изменении
импортов иногда возникает рассинхронизация.
Типичные причины:
- переименование файлов без пересборки
- изменения в алиасах (
package.json#alias,
.babelrc, tsconfig.paths)
- переключение веток Git без очистки кэша
Проявление:
- «Cannot resolve module» для существующих файлов
- дублирование модулей в сборке
- некорректный HMR-обновляемый модуль
Проблемы с HMR (Hot
Module Replacement)
HMR зависит от корректной идентификации модулей в кэше.
Ошибки возникают при:
- изменении структуры экспорта/импорта
- замене React-компонентов с изменением типа экспорта
- использовании динамических импортов без стабильных путей
Проявление:
- страница не обновляется при изменении кода
- происходит полная перезагрузка вместо HMR
- потеря состояния приложения без причины
Конфликты между окружениями
Кэш Parcel привязан к окружению сборки. Перенос проекта между
системами может приводить к несоответствиям.
Факторы:
- различия ОС (Windows / Linux / macOS)
- различия файловой системы (case-sensitive / case-insensitive)
- различия версий Node.js
- использование Docker без очистки volume с кэшем
Проявление:
- ошибки, которые не воспроизводятся локально на другой машине
- случайные падения сборки
- некорректные пути к модулям
Проблемы с
production build и cache busting
Parcel автоматически добавляет content hashing в
production-режиме:
app.8f3a1c2d.js
style.91b7d0e.css
Однако ошибки возникают при внешнем кэшировании:
- CDN не учитывает изменения хеша
- Service Worker продолжает отдавать старые файлы
- неправильные настройки cache-control headers
Проявление:
- пользователи видят старую версию приложения
- обновления «не доходят» до клиентов
- конфликт версий ассетов
Причины возникновения
кэш-проблем
1. Изменение
конфигурации без очистки кэша
Parcel не всегда может корректно определить влияние изменений в
конфигурационных файлах:
.babelrctsconfig.json.postcssrc.env
Особенно критично при изменении:
- плагинов Babel
- target environment
- polyfill настроек
2. Обновление зависимостей
После обновления:
- Parcel
- Babel
- TypeScript
- PostCSS плагинов
старый кэш может содержать несовместимые трансформации.
3. Переключение Git-веток
При частых переключениях веток остаются:
- старые артефакты сборки
- несовместимые версии модулей
- устаревший dependency graph
4. Повреждение кэша
Редкий, но критический случай:
- прерывание сборки
- нехватка места на диске
- ошибки файловой системы
Методы диагностики
кэш-проблем
Проверка режима
инкрементальной сборки
Если Parcel ведёт себя нестабильно, следует определить:
- изменяется ли hash файла в output
- пересобирается ли модуль при изменении исходника
- обновляется ли HMR
Запуск без кэша
Parcel можно запустить с отключением кэша:
parcel build src/index.html --no-cache
или удалить директорию:
rm -rf .parcel-cache
Это позволяет проверить, связана ли проблема именно с
кэшированием.
Анализ зависимостей
При подозрении на рассинхронизацию графа модулей:
- проверить корректность импортов
- удалить
dist и .parcel-cache
- перезапустить сборку
Решение проблем с кэшем
Полная очистка кэша Parcel
Стандартный способ устранения большинства проблем:
rm -rf .parcel-cache dist
После этого выполняется полная пересборка проекта.
Принудительная
пересборка зависимостей
В сложных случаях требуется:
- удаление
node_modules
- переустановка зависимостей
rm -rf node_modules package-lock.json
npm install
Синхронизация конфигурации
Важно обеспечить согласованность:
- Babel presets и plugins
- TypeScript версии и настройки
- PostCSS конфигурации
Несовместимость этих слоёв часто приводит к тому, что кэш становится
«логически валидным», но фактически неверным.
Управление кешированием в
CI/CD
В системах сборки необходимо осторожно использовать кеширование:
- кэшировать
.parcel-cache только при стабильной
конфигурации
- инвалидировать кэш при изменении lock-файлов
- разделять кэш по веткам или хешу commit
Работа с Service Worker
При использовании PWA:
- обновление Service Worker должно учитывать новые хеши ассетов
- необходимо контролировать стратегию cache-first / network-first
- важно корректно обновлять cache storage
Иначе Parcel будет корректно собирать новые файлы, но браузер
продолжит использовать старые версии.
Особенности
поведения Parcel при кэшировании
Parcel использует подход «content-aware caching», при котором:
- файл пересобирается только при изменении содержимого или
зависимостей
- учитывается не только исходный код, но и результат
трансформаций
- кэш привязан к конкретной версии пайплайна сборки
Это делает систему быстрой, но чувствительной к любым изменениям
окружения.
Типовые сценарии ошибок
и их источники
Сценарий 1: код изменён, но результат не
меняется
- причина: stale transform cache
- решение: очистка
.parcel-cache
Сценарий 2: ошибка импорта существующего файла
- причина: устаревший dependency graph
- решение: удаление кэша и перезапуск
Сценарий 3: HMR перестаёт работать
- причина: нарушение стабильности модулей
- решение: проверка экспортов и очистка кэша
Сценарий 4: production показывает старую версию
- причина: CDN или Service Worker
- решение: настройка cache headers и инвалидизация ассетов
Принципы устойчивой работы с
кэшем
- кэш должен рассматриваться как производный артефакт, а не источник
истины
- любые изменения toolchain требуют его инвалидизации
- стабильность HMR зависит от стабильности модульной структуры
- production-кэширование должно контролироваться отдельно от
Parcel
Поведение при изменении
версии Parcel
При обновлении Parcel:
- старый
.parcel-cache часто становится
несовместимым
- возможны скрытые ошибки сборки
- требуется полная очистка артефактов
Особенно критично при переходе между мажорными версиями, где меняется
внутренняя структура графа модулей и механизм трансформаций.