O que são builds multi-estágio e por que usá-los?

Question

Accepted Answer

**Builds multi-estágio** usam múltiplos estágios `FROM` em um único Dockerfile — construindo a aplicação em um estágio (com todas as ferramentas de build) e copiando apenas os artefatos finais para um estágio final limpo e minimalista. Isso produz imagens de produção **muito menores e mais seguras**.

## O problema: ferramentas de build incham a imagem

```text
Building an app needs build tools (compilers, dev dependencies, SDKs), but the
FINAL image shouldn't include them:
  → they bloat the image (larger size, slower deploys)
  → they increase the attack surface (more software = more vulnerabilities)
→ You want only the built artifact + its runtime in the final image.
```

## Build multi-estágio

```dockerfile
# STAGE 1: "build" — has all the build tools (compile/bundle the app)
FROM node:20 AS build
WORKDIR /app
COPY package*.json ./
RUN npm install              # includes dev dependencies, build tools
COPY . .
RUN npm run build            # produces /app/dist

# STAGE 2: final — a clean, minimal image with ONLY the built artifact
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html   # copy ONLY the build output
# → the final image has NO build tools, no dev dependencies — just nginx + the built files
```

O `--from=build` copia artefatos do estágio de build para a imagem final. A imagem final **exclui tudo do estágio de build exceto aquilo que você copia explicitamente** — então ferramentas de build, dependências de desenvolvimento e código-fonte não acabam na produção.

## Benefícios

```text
✓ SMALLER images — only the runtime + artifacts (often 10x+ smaller)
✓ More SECURE — fewer packages = smaller attack surface (no compilers/build tools)
✓ Faster deploys/pulls (smaller images transfer faster)
✓ One Dockerfile — build and final image together (no separate build scripts)
→ Common for compiled languages (Go, Rust, Java) and Node/frontend builds.
```

## Por que isso importa

Compreender builds multi-estágio é valioso para **produzir imagens de produção pequenas e seguras**, portanto é um conhecimento prático importante para construir imagens Docker com qualidade de produção.

O problema que resolve é real e comum: construir uma aplicação requer **ferramentas de build** (compiladores, SDKs, dependências de desenvolvimento) que a **imagem de produção final não deveria conter** — incluí-las incha a imagem (tamanho maior, deployments e pulls mais lentos) e aumenta a **superfície de ataque** (mais software instalado significa mais vulnerabilidades potenciais). **Builds multi-estágio** resolvem isso elegantemente usando múltiplos estágios `FROM`: construindo a aplicação em um estágio com todas as ferramentas, depois **copiando apenas os artefatos finais** (`--from=build`) para um estágio final limpo e minimalista que exclui tudo mais.

Isso produz imagens que são **dramaticamente menores** (frequentemente 10x+ menores — apenas o runtime e artefatos) e **mais seguras** (sem ferramentas de build ou pacotes desnecessários para explorar), enquanto mantém tudo em um único Dockerfile (sem scripts de build separados).

Este padrão é padrão para linguagens compiladas (Go, Rust, Java, onde o compilador não é necessário em tempo de execução) e para builds frontend/Node (onde ferramentas de build e código-fonte não são necessários em produção).

Como imagens de produção pequenas e seguras importam para velocidade de deployment, armazenamento e segurança, e como builds multi-estágio são a técnica padrão e eficaz para alcançá-las (separando o ambiente de build da imagem de runtime enxuta), compreender builds multi-estágio — o problema de inchaço/segurança que resolvem, como funcionam e seus benefícios — é conhecimento valioso, frequentemente aplicado para construir imagens Docker com qualidade de produção, uma best practice amplamente usada em Dockerfiles do mundo real e uma habilidade-chave para produzir aplicações containerizadas eficientes e seguras.