re:re:actable
Урок 033 минуты чтения

Как работают слои и кэш сборки

На этой странице
Кратко

Образ состоит из слоёв — каждый 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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам