Imagens, camadas e cache de build

Cada instrução do Dockerfile (RUN, COPY...) gera uma camada — empilhada sobre a anterior. Docker guarda cache dessas camadas: se uma instrução e tudo que veio antes dela não mudou, o build reusa o resultado em cache em vez de reexecutar. Isso é a diferença entre um rebuild de 2 segundos e um de 2 minutos.

O erro clássico: copiar tudo antes de instalar dependência

FROM node:20-alpine
WORKDIR /app
COPY . .                              # QUALQUER mudança de código invalida esta camada
RUN corepack enable && pnpm install   # ...e força reinstalar TODAS as dependências de novo

Como COPY . . copia o projeto inteiro, qualquer arquivo alterado (até um .md sem relação nenhuma com dependência) invalida essa camada — e Docker invalida tudo depois dela também, incluindo o pnpm install, que reinstala tudo do zero mesmo que nenhuma dependência tenha mudado.

A correção: copiar só o que o install precisa, primeiro

FROM node:20-alpine
WORKDIR /app

COPY package.json pnpm-lock.yaml ./      # só isso muda quando dependência muda
RUN corepack enable && pnpm install --frozen-lockfile

COPY . .                                  # mudança de código não afeta mais o install acima
RUN pnpm build

Agora pnpm install só reroda quando package.json/pnpm-lock.yaml mudam de verdade — mudar um componente React não invalida mais essa camada, e o rebuild pula direto pro que realmente mudou.