# Cache de camadas do Docker explicado: builds de imagem mais rápidos no CI

> O Docker constrói imagens em camadas com cache, reutilizando as inalteradas para evitar trabalho. Entenda como o cache de camadas funciona e como ordenar um Dockerfile para acertar o cache.

Source: https://latchkey.dev/pt/learn/ci-cd-concepts/docker-layer-caching-explained  
Updated: 2026-06-25

O Docker constrói uma imagem como uma pilha de camadas com cache. Ordene seu Dockerfile para que as partes que raramente mudam venham primeiro, e a maioria dos builds reutiliza quase tudo.

Cada instrução em um Dockerfile produz uma camada. O Docker pode reutilizar uma camada de um build anterior se suas entradas não mudaram - mas uma única alteração no início invalida tudo depois dela. A ordenação é tudo.

## Como as camadas são cacheadas

O Docker faz hash de cada instrução e suas entradas. Se o hash corresponder a uma camada em cache, ele a reutiliza em vez de reexecutar o step. No momento em que as entradas de uma camada mudam, essa camada e todas as abaixo são reconstruídas - o cache é invalidado para baixo, não seletivamente.

## Ordenar para acertar o cache

Coloque as instruções estáveis primeiro e as voláteis por último. Copie seu manifesto de dependências e instale as dependências *antes* de copiar o source da aplicação, para que uma alteração de código não estrague a camada de instalação de dependências.

```Cache-friendly ordering
COPY package*.json ./
RUN npm ci          # cached unless deps change
COPY . .            # changes often; only this layer rebuilds
RUN npm run build
```

## Por que o CI costuma errar o cache

- Runners efêmeros começam sem cache local de imagem a cada execução.
- Nenhum backend de cache externo configurado, então nada é restaurado.
- Copiar o source antes de instalar as deps, invalidando as deps a cada commit.
- Um build argument variável perto do topo do arquivo estragando tudo.

## Cache entre execuções de CI

Como runners efêmeros não têm cache local, você precisa de um externo: o cache baseado em registry do BuildKit (`--cache-from` / `--cache-to`) armazena camadas em um registry para que a próxima execução as restaure. Sem isso, todo build de CI é efetivamente um build a frio.

## FAQ

### What is Docker layer caching Explained: faster image builds in CI?

Each instruction in a Dockerfile produces a layer. Docker can reuse a layer from a previous build if its inputs are unchanged - but a single early change invalidates everything after it. Ordering is everything.

### How layers are cached?

Docker hashes each instruction and its inputs. If the hash matches a cached layer, it reuses it instead of re-running the step. The moment one layer’s inputs change, that layer and every layer below it are rebuilt - the cache is invalidated downward, not selectively.

### Order for cache hits?

Put stable instructions first and volatile ones last. Copy your dependency manifest and install dependencies *before* copying your application source, so a code change does not bust the dependency-install layer.

### Caching across CI runs?

Because ephemeral runners have no local cache, you need an external one: BuildKit’s registry-backed cache (--cache-from / --cache-to) stores layers in a registry so the next run restores them. Without that, every CI build is effectively a cold build.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt