Что даёт кэширование зависимостей и что именно кэшировать
Кэш возвращает пайплайну то, что он теряет между запусками: скачанные пакеты, собранные нативные модули, слои образа, редко меняющиеся бинарники. Ускорение появляется при одном условии: ключ кэша привязан к содержимому lock-файла. Ключ по номеру сборки или по текущей дате даёт либо постоянные промахи, либо устаревшие зависимости в сборке, которая при этом выглядит зелёной.
Дальше разбираем, что кэшировать в первую очередь, как построить ключ по lock-файлу, как это выглядит в GitLab CI и GitHub Actions, какие три ошибки чаще всего превращают кэш в источник ложных срабатываний и какими командами проверить результат.
Примеры записаны для конкретных окружений: GitLab CI с раннером Docker executor, GitHub Actions с actions/cache@v4, Node.js 22 и npm 10, Python 3.12 с pip 24. Синтаксис полей, пути и поведение кэша зависят от версии платформы и пакетного менеджера, поэтому сверяйте блок с документацией своего окружения перед копированием.
Почему без кэша пайплайн каждый раз начинает с нуля
Хостинговый раннер выдаёт чистую виртуальную машину или контейнер на каждый job. Каталоги ~/.npm, ~/.cache/pip, ~/.m2, ~/.gradle в нём пусты. Self-hosted раннер с Docker executor ведёт себя так же, пока вы не примонтируете volume или не включите кэш явно.
Время job складывается из четырёх частей: скачивание архивов пакетов, разрешение графа зависимостей, компиляция нативных модулей (node-gyp, сборка wheel из исходников) и post-install скрипты. Кэш убирает первую часть и часто третью. Разрешение зависимостей остаётся: пакетный менеджер всё равно сверяет lock-файл.
Цифры ускорения не переносятся с проекта на проект. Они зависят от числа зависимостей, скорости сети раннера и наличия нативных модулей, поэтому сначала измерьте свою базовую линию по схеме из раздела про проверку, затем включайте кэш.
Пакетный менеджер, слои сборки и инструменты: что кэшировать в первую очередь
Начинайте с кэша пакетного менеджера: он даёт выигрыш быстрее всего и требует меньше всего правок. Кэшируйте глобальный store, а не рабочую директорию проекта.
- Кэш пакетного менеджера. npm хранит архивы в ~/.npm (в GitLab CI удобно перенести его внутрь проекта флагом --cache .npm), pnpm — в store, путь к которому печатает pnpm store path, pip — в ~/.cache/pip (Linux, путь печатает pip cache dir), Maven — в ~/.m2/repository, Gradle — в ~/.gradle/caches и ~/.gradle/wrapper.
- Слои Docker-сборки. BuildKit кэширует промежуточные слои, и при неизменном слое с зависимостями повторная сборка не выполняет установку пакетов заново. Кэш экспортируется в registry или в хранилище CI (--cache-to type=registry, cache-to: type=gha для build-push-action). Порядок инструкций в Dockerfile разбираем отдельно в статье про кэширование слоёв Dockerfile.
- Инструменты сборки. Бинарники линтеров, плагины Terraform, компиляторы и SDK меняются редко, поэтому их каталоги стоит кэшировать с ключом, включающим версию инструмента. Изменение версии должно менять ключ, иначе вы получите старый бинарник при обновлённом конфиге.
Кэш node_modules целиком оправдан не всегда. При частой смене lock-файла и нативных модулях выгоднее кэшировать store пакетного менеджера: он переносимее и менее чувствителен к различиям окружений.
| Что кэшировать | Что не кэшировать | Почему |
|---|---|---|
| Store npm, pnpm, yarn, pip, Maven, Gradle | Секреты, .env, приватные ключи | Кэш читают другие job и ветки, секрет в нём превращается в утечку |
| Слои Docker-сборки | Артефакты сборки (dist/, target/) | Результат должен пересобираться из текущего кода, иначе тесты проверяют прошлый коммит |
| Бинарники линтеров, плагины Terraform, SDK | node_modules при ежедневной смене lock-файла | Почти не экономит время и повышает риск несовместимости нативных модулей |
| Каталог загрузок пакетного менеджера с ключом по версии | Логи, отчёты покрытия, временные файлы | Растут каждый запуск, вытесняют полезные записи из кэша |
Ключ кэша по lock-файлу: как сделать инвалидацию предсказуемой
Ключ кэша должен зависеть от содержимого lock-файла: package-lock.json, pnpm-lock.yaml, yarn.lock, poetry.lock, pom.xml, а для pip — от файла с зафиксированными версиями и хешами. Схема простая: префикс с именем пакетного менеджера и окружения плюс хеш lock-файла. Ключ вида npm-linux-<хеш package-lock.json> меняется только тогда, когда меняется набор зависимостей.
Хешируйте lock-файл, а не manifest. В package.json или pyproject.toml версии часто заданы диапазонами, и файл не меняется при обновлении транзитивных зависимостей. Кэш при этом останется прежним, а сборка будет ссылаться на старые пакеты.
Промах после правки lock-файла — ожидаемое поведение, а не ошибка. Первый запуск после обновления зависимостей будет медленнее, зато второй снова попадёт в кэш.
Почему ключ по номеру сборки или по дате не работает
Два антипаттерна дают противоположные и одинаково неприятные результаты.
- Ключ, который никогда не меняется. Например, константа npm-cache или ключ по имени проекта. Кэш не инвалидируется, в сборку попадают устаревшие зависимости, тесты проходят на старом дереве пакетов и дают ложноположительный результат.
- Ключ, который меняется каждый запуск. Номер сборки, CI_PIPELINE_ID, текущая дата. Промах гарантирован всегда: кэш записывается, но не переиспользуется, а время тратится на сохранение и загрузку архива.
Хеш lock-файла снимает обе проблемы: ключ стабилен между запусками и меняется ровно при изменении зависимостей.
Fallback-ключи и частичное восстановление кэша
После обновления lock-файла точный ключ промахивается, и job качает всё с нуля. Частично ускорить первый запуск помогают fallback-ключи: при промахе CI ищет запись по префиксу ключа, восстанавливает её, а пакетный менеджер докачивает недостающие версии. В GitHub Actions это restore-keys, в GitLab CI — cache:key:prefix вместе с cache:key:files.
Осторожность нужна в двух местах. Fallback подходит для пакетных менеджеров, которые корректно доустанавливают пакеты поверх частичного store: npm, pnpm и pip с этим справляются, а вот нативные модули, собранные под другую версию ABI Node.js или другой дистрибутив, могут дать ошибку при загрузке. Второй момент: слишком широкий префикс притягивает кэш чужой ветки. Ограничивайте префикс именем пакетного менеджера, ОС и, если нужно, веткой.
key: npm-Linux-${{ hashFiles('package-lock.json') }}
restore-keys: |
npm-Linux-
Синтаксис и поддержка fallback зависят от платформы, проверьте поля по документации вашей версии CI.
Кэш зависимостей в GitLab CI: пример конфигурации
В GitLab CI кэш описывается секцией cache в job. Поля cache:key:files, cache:paths и cache:policy поддерживаются давно, но нюансы слияния при extends стоит сверить с версией вашего GitLab.
.npm_cache:
cache:
key:
files:
- package-lock.json
prefix: npm-$CI_COMMIT_REF_SLUG
paths:
- .npm/
policy: pull-push
build:
extends: .npm_cache
stage: build
image: node:22
script:
- npm ci --cache .npm --prefer-offline --no-audit
- npm run build
artifacts:
paths:
- dist/
test:
extends: .npm_cache
stage: test
image: node:22
cache:
policy: pull
script:
- npm ci --cache .npm --prefer-offline --no-audit
- npm test
Что здесь важно:
- cache:key:files заставляет GitLab вычислить новый ключ кэша при изменении содержимого перечисленных файлов. Пока содержимое не меняется, ключ остаётся неизменным между ветками и пайплайнами, поэтому кэш переиспользуется. При изменении файла вычисляется новый ключ и создаётся новый кэш, который подхватывают последующие запуски (CI/CD YAML syntax reference, GitLab Docs).
- Ключ по файлам строится на SHA от последнего коммита для каждого указанного файла; несуществующие файлы при расчёте игнорируются. Поэтому опечатка в имени файла не даст ошибку, но и не привяжет ключ к нужному lock-файлу — проверяйте имена.
- prefix с CI_COMMIT_REF_SLUG привязывает кэш к ветке. Без префикса кэш с одинаковым ключом доступен разным веткам, и зависимость из feature-ветки может попасть в сборку main.
- policy: pull в тестах экономит время: job только читает кэш и не пытается перезаписать его наперегонки с другими job. Запись оставьте одному job с pull-push.
- cache и artifacts решают разные задачи. Кэш ускоряет повторные запуски и не гарантирует наличие файлов, артефакты передают результат сборки между job и хранятся как результат пайплайна.
По умолчанию защищённые и незащищённые ветки не разделяют кэш: разделение кэшей для защищённых веток — это функция безопасности, и она включена. Отключить её можно в настройках проекта, сняв опцию раздельных кэшей для защищённых ветвей, — тогда все ветки используют один кэш (Caching in GitLab CI/CD, GitLab Docs). Отключайте осознанно: общий кэш удобнее для попаданий, но снимает изоляцию, которая не даёт незащищённой ветке влиять на кэш, читаемый защищённой веткой.
Проверка: откройте лог job и найдите строки со словом cache. При попадании раннер пишет, что проверяет кэш по ключу и успешно распаковывает архив, при промахе сообщает об отсутствии записи, после job появляется сообщение о создании кэша. Формулировки различаются между версиями раннера, ориентируйтесь на ключ кэша в строке и на слово cache.
Кэширование в GitHub Actions: пример с actions/cache
Для Node.js проще всего встроенный кэш setup-node: он сам считает ключ по lock-файлу и восстанавливает store npm.
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
cache-dependency-path: package-lock.json
Ручной вариант через actions/cache@v4 даёт контроль над ключом и путями. Версию экшена фиксируйте: синтаксис между мажорными версиями меняется.
- name: Cache npm store
uses: actions/cache@v4
with:
path: ~/.npm
key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
restore-keys: |
npm-${{ runner.os }}-
- name: Install dependencies
run: npm ci --prefer-offline --no-audit
Проверьте шаблон пути: **/package-lock.json нужен только для монорепозитория, в обычном проекте достаточно package-lock.json. Если шаблон не совпадает ни с одним файлом, ключ теряет привязку к lock-файлу и совпадает у всех запусков — это ровно тот антипаттерн с устаревшими зависимостями. Поведение hashFiles при отсутствии совпадений сверяйте с документацией вашей версии GitHub Actions.
restore-keys проверяются последовательно: если ключ не совпал напрямую, выполняется поиск ключей с префиксом ключа восстановления, а при нескольких частичных совпадениях возвращается последний созданный кэш. Поэтому порядок и ширина префиксов в списке влияют на то, какой кэш вы получите (Справочник по кэшированию зависимостей, GitHub Docs).
Область видимости в GitHub Actions устроена иначе, чем в GitLab CI: кэш ограничен ключом, путями и веткой, а кэш ветки по умолчанию доступен другим веткам (actions/cache, GitHub). Кэш, созданный при запуске workflow по pull request, создаётся для ссылки слияния и может быть восстановлен только повторным запуском того же pull request — базовой веткой или другими pull request'ами он не подхватывается.
Хранилище кэша тоже ограничено. GitHub удаляет записи, к которым не обращались более 7 дней. По умолчанию общий размер всех кэшей в репозитории ограничен 10 ГБ, и этот лимит могут увеличить владельцы enterprise/организации или администраторы репозитория. При достижении максимума действует политика вытеснения: кэши удаляются в порядке даты последнего доступа от самой старой к самой новой, а новый кэш сохраняется (Dependency caching reference, GitHub Docs). В настройках GitHub Actions для репозитория можно задать срок хранения кэшей (по умолчанию 7 дней, до 90 дней для публичных и до 365 дней для приватных и внутренних репозиториев) и лимит вытеснения размера кэша (по умолчанию 10 ГБ, до 10 000 ГБ на репозиторий) (Управление настройками GitHub Actions для репозитория, GitHub Docs).
Проверка: в логе шага кэширования ищите строки с ключом. При попадании появляется сообщение о восстановлении кэша с конкретным ключом, при промахе — сообщение, что кэш по указанным ключам не найден, а в пост-шаге job будет запись о сохранении. Практический тест: запустите workflow дважды без правок, затем измените версию одной зависимости в package-lock.json и убедитесь, что третий запуск промахнулся.
Для Docker-сборки в Actions кэш слоёв укладывается в хранилище GitHub через buildx и build-push-action с cache-to: type=gha. Схему для нескольких сервисов и registry разбираем в материале про кэширование в Docker и Kubernetes.
Типичные ошибки кэширования и как их избежать
Три конфигурации дают большинство инцидентов: кэш без инвалидации, секреты внутри кэшируемых путей и общий кэш для всех ветвей.
Кэш без инвалидации: почему сборка «зелёная», а зависимости старые
Сценарий: lock-файл обновили, ключ кэша остался прежним, job восстановил старый store и поставил пакеты из него. Тесты прошли, релиз ушёл, а на проде другая версия библиотеки. Риск в том, что такой сбой не виден в логах: job зелёный, время пайплайна даже улучшилось.
Исправление: ключ по хешу lock-файла и версия в префиксе для ручного сброса (npm-v2-...). Дополнительно проверяйте, что после установки версия критичной зависимости совпадает с ожидаемой, например через npm ls <пакет> или вывод pip freeze в лог.
Секреты в кэше: как не превратить ускорение в утечку
В кэш не должны попадать .env, файлы с токенами, приватные ключи, конфиги с паролями, а также каталоги, куда пакетный менеджер или скрипт складывает учётные данные (.npmrc с токеном registry, pip.conf с паролем).
Кэш читают другие job и, при совпадении ключа, другие ветки. Токен, осевший в кэше, доступен тому, кто может запустить пайплайн в этом репозитории, а также тому, кто читает хранилище кэша напрямую.
Держите секреты в защищённых переменных CI и передавайте их в момент выполнения, не записывая на диск в кэшируемых путях. В примерах используйте очевидные заглушки:
npm config set //registry.example.com/:_authToken "${NPM_TOKEN_PLACEHOLDER}"
Заглушка ${NPM_TOKEN_PLACEHOLDER} демонстрирует синтаксис, реальный токен подставляется из переменной CI и в репозиторий не попадает. Если пакетный менеджер пишет токен в файл в домашней директории, исключите этот файл из путей кэша.
Грязный кэш между ветками: изоляция и область видимости
Общий ключ для всех ветвей приводит к невоспроизводимым сборкам: в main приезжает store, собранный в feature-ветке, а там могли быть другие версии транзитивных зависимостей или пакеты из локального registry.
Привязывайте ключ к ветке (CI_COMMIT_REF_SLUG в GitLab CI, github.ref_name в GitHub Actions) и используйте раздельные кэши для защищённых ветвей. Компромисс очевиден: изоляция по веткам снижает долю попаданий, зато результат сборки перестаёт зависеть от чужих экспериментов. Для долгоживущих веток допустим общий префикс по ветке, для коротких feature-веток хватает точного ключа по lock-файлу.
Как проверить, что кэш работает и не даёт ложных срабатываний
Проверка занимает три шага и не требует отдельных инструментов.
- Базовая линия. Выключите кэш и прогоните пайплайн 3 раза подряд на одинаковом коммите. Запишите длительность job установки зависимостей и общую длительность пайплайна. Три запуска нужны, чтобы отсечь разброс сети раннера.
- Замер с кэшем. Включите кэш и повторите 3 запуска. Второй и третий должны попадать в кэш; первый после включения кэша попадать не может, записи ещё нет.
- Проверка инвалидации. Измените одну версию в lock-файле, запустите пайплайн и убедитесь, что кэш промахнулся, а после job сохранился под новым ключом.
Попадание в кэш определяется по логу job: ищите ключ кэша и слова cache, restored, extracted, not found, cache is empty. Точные формулировки отличаются между версиями GitLab Runner, GitHub Actions и экшенов, поэтому ориентируйтесь на свой ключ в строке лога, а не на заученную фразу.
| Этап | Время до кэша | Время после | Попадание в кэш |
|---|---|---|---|
| Установка зависимостей | замер 1 | замер 2 | hit по ключу с хешем lock-файла |
| Сборка проекта | замер 1 | замер 2 | не кэшируется, время не должно падать |
| Тесты | замер 1 | замер 2 | hit, политика pull |
| Первый запуск после смены lock-файла | замер 1 | замер 2 | miss, ожидаемо |
Цифры у каждого свои: они зависят от числа зависимостей, сети и наличия нативных модулей. Полезный сигнал не абсолютная секунда, а устойчивое сокращение этапа установки при неизменном времени остальных этапов. Если время сборки тоже резко упало, проверьте, не попали ли артефакты в кэш.
Для диагностики неожиданных промахов и устаревших данных пригодится материал про ошибки кэширования и их диагностику.
Чек-лист и когда кэш лучше отключить
Проверьте пункты перед включением кэша в общий пайплайн.
- Ключ кэша содержит хеш lock-файла, а не номер сборки, дату или константу.
- В путях кэша нет .env, .npmrc с токеном, приватных ключей и каталогов с учётными данными.
- Область видимости ограничена: префикс по ветке или раздельные кэши для защищённых ветвей.
- Есть ручной сброс: версия в префиксе ключа (npm-v2-...) увеличивается одной строкой.
- Проверены попадание и промах по логу, а также поведение после правки lock-файла.
- Время пайплайна измерено до и после на 3 запусках.
- Запись кэша выполняет один job, остальные работают с политикой чтения.
Кэш вредит в трёх случаях. На очень коротких пайплайнах, где сохранение и распаковка архива занимают столько же времени, сколько установка пакетов. В проектах с ежедневной сменой lock-файла, где почти каждый запуск промахивается. И там, где нужна абсолютная воспроизводимость с нуля, например в аудите релизной сборки: тогда имеет смысл отдельный пайплайн без кэша.
Ручной сброс выполняйте осознанно. В GitLab CI кэш раннеров очищается кнопкой в настройках CI/CD проекта, в GitHub Actions кэш удаляется через интерфейс или командой gh cache delete --all (свериться с версией gh CLI). Обе операции затрагивают все кэши проекта или репозитория: ближайшие пайплайны пойдут без кэша и станут медленнее, а другие команды получат точно такое же замедление. Если нужно точечно, меняйте версию в префиксе ключа вместо полной очистки.