Build Cache Strategies

Layer Cache Mechanics

A layer is reused when its parent layer, instruction text, build args, and file contents are unchanged. That gives the ordering rule — put infrequently changing work first:

FROM node:20-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci              # cached until the lockfile changes
COPY src ./src          # invalidated on every source commit
RUN npm run build

Everything after a changed COPY re-runs, so a single misplaced COPY . . above npm ci defeats the whole cache. Inspect reality with docker build --progress=plain and look for CACHED on each step.

BuildKit Cache Mounts

Cache mounts survive even when the layer itself is invalidated, because the cache lives outside the layer graph:

RUN --mount=type=cache,target=/root/.npm npm ci
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    apt-get update && apt-get install -y --no-install-recommends git

The npm cache and apt lists persist across commits and branches. sharing=locked makes concurrent builders take turns on a mount that cannot tolerate parallel writers; use the default shared for read-heavy caches. Bind mounts (type=bind,from=) instead inject build-time context without committing it to a layer.

External Caches and Pitfalls

To reuse cache across machines, export it:

docker buildx build \
  --cache-to type=registry,ref=registry.example.com/app:buildcache,mode=max \
  --cache-from type=registry,ref=registry.example.com/app:buildcache .

mode=max exports intermediate stages; without it only final layers ship. Inline cache (--build-arg BUILDKIT_INLINE_CACHE=1) embeds cache metadata in the pushed image itself, which only helps for single-stage or final-stage reuse.

Pitfalls. Registries expire old manifests, so cold caches return silently; secrets must never ride in cached layers (--mount=type=secret); and a polluted builder disk is fixed with docker builder prune, not by deleting your Dockerfile.