Как работают слои и кэш сборки
На этой странице
Образ состоит из слоёв — каждый RUN, COPY и ADD добавляет слой с изменениями файловой системы. При повторной сборке BuildKit переиспользует слой из кэша, если инструкция и её входные данные (для COPY — содержимое файлов) не изменились. Кэш инвалидируется каскадно: изменился один слой — пересобираются все ниже. Поэтому зависимости устанавливают до копирования исходников, а для кэша менеджера пакетов используют RUN --mount=type=cache.
Вопрос
Как устроены слои образа и как работает кэш сборки?
Основная идея
FROM node:24-alpine # слои базового образа
WORKDIR /app # метаданные
COPY package.json package-lock.json ./ # слой: 2 файла
RUN npm ci # слой: node_modules
COPY . . # слой: исходники
RUN npm run build # слой: distПри правке src/index.ts меняется только содержимое COPY . .:
FROM ... CACHED
COPY package*.json CACHED
RUN npm ci CACHED ← самый дорогой шаг пропущен
COPY . . пересобирается
RUN npm run build пересобираетсяКогда кэш инвалидируется
- Для
COPY/ADD— изменилось содержимое или метаданные копируемых файлов. - Для
RUN— изменился текст команды. Docker не знает, чтоapt-get updateсегодня вернёт другие пакеты: строка та же — значит, кэш. - Изменился любой слой выше.
- Изменился
ARG, используемый в инструкции.
Отсюда классическая ловушка:
# Плохо: update закэшируется навсегда, install однажды найдёт устаревшие индексы
RUN apt-get update
RUN apt-get install -y curl
# Хорошо: одна инструкция, кэш общий
RUN apt-get update && apt-get install -y --no-install-recommends curl \
&& rm -rf /var/lib/apt/lists/*Размер слоёв
Удаление в отдельной инструкции не уменьшает образ — файл остаётся в нижнем слое:
RUN npm ci && npm cache clean --force # кэш не попадёт в слой
# а не
RUN npm ci
RUN npm cache clean --force # слой выше лишь «прячет» файлыdocker image history my-api # какие инструкции создали большие слоиCache mount
# syntax=docker/dockerfile:1
FROM node:24-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .Кэш npm хранится между сборками на стороне builder, но не попадает в образ. Даже когда lock-файл изменился и npm ci выполняется заново, пакеты берутся из локального кэша, а не из сети. Для pnpm целевой каталог — /root/.local/share/pnpm/store, для apt — /var/cache/apt.
Кэш в CI
В CI каждый запуск — чистая машина, локального кэша нет. Его сохраняют во внешнее хранилище:
docker buildx build \
--cache-from type=registry,ref=ghcr.io/team/api:buildcache \
--cache-to type=registry,ref=ghcr.io/team/api:buildcache,mode=max \
-t ghcr.io/team/api:${GIT_SHA} --push .В GitHub Actions удобен type=gha.
Частые ошибки
COPY . .передnpm ci.- Отсутствие lock-файла — каждая сборка ставит разные версии.
- Раздельные
apt-get updateиapt-get install. - Удаление временных файлов отдельным
RUN. - Отсутствие
.dockerignore: изменение любого лога ломает кэшCOPY . ..
Что важно помнить
- Кэш проверяется сверху вниз и обрывается на первом изменившемся слое.
- Docker сравнивает текст
RUN, а не результат команды. --no-cache— пересобрать всё,--pull— заодно скачать свежий базовый образ.
Мини-шпаргалка
- Lock-файлы →
npm ci→ код. - Изменение слоя пересобирает все слои ниже.
- Чистить кэш в той же инструкции.
RUN --mount=type=cache— кэш пакетов вне образа.- В CI:
--cache-from/--cache-to.
Документация
Docker: Build cache, Docker: Optimize cache usage, Docker: Cache storage backends.