Optimización de Multi-Stage Builds en Docker
Reduce el tamaño de imagen y el tiempo de build con multi-stage builds, orden de capas inteligente, cache mounts de BuildKit y un .dockerignore ajustado.
Visión General
Un Dockerfile multi-stage compila tu app en una etapa llena de toolchain y copia solo los artefactos necesarios a una etapa final mínima. Bien hecho, eso ya recorta imágenes un 80-90 por ciento — un servicio Go baja de ~1.2GB con golang:1.22 a ~15MB sobre scratch. Pero el tamaño es solo la mitad del beneficio: el mismo archivo, ordenado mal, también reconstruye tu capa de dependencias en cada commit. Esta receta cubre las dos mitades — achicar la imagen que se publica y el tiempo que tarda en construirse.
Dockerfiles ejecutables para cada ejemplo en el repositorio complementario. Para el deep dive en bases mínimas sin shell, mira imágenes distroless con multi-stage builds — esta página se queda en el lado de la optimización: orden de capas, cachés y velocidad de build.
Cuándo Usar
- Tu imagen pasa de ~500MB para una app simple, o
docker imageste sorprende - Compiladores, SDKs o
node_modulesse publican a producción - Los builds de CI tardan minutos porque la instalación de dependencias se repite en cada commit
- Build y runtime necesitan bases distintas —
golangpara compilar,scratcho distroless para correr
Cuándo NO Usar
- Scripts de un archivo y contenedores desechables — una segunda etapa no aporta nada
- Apps que de verdad necesitan su toolchain en runtime (algunos servicios de compilación, hosts de plugins)
- Si tu único problema son los fallos de caché en CI, un
--mount=type=cachepuede bastar sin reestructurar nada
Solución
Multi-stage build para Node.js
# Stage 1: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Stage 2: Producción
FROM node:20-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
npm ci --omit=dev en la etapa final reinstala solo las dependencias de producción — las devDependencies nunca cruzan el FROM. Podar node_modules en el builder y copiarlo entero parece más corto, pero arrastra las dev deps y rompe la caché de capas de otra forma; reinstalar desde el lockfile es más limpio.
Multi-stage para Python con runtime mínimo
# Stage 1: Build dependencias
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --target=/opt/deps -r requirements.txt
# Stage 2: Runtime
FROM gcr.io/distroless/python3-debian12 AS runtime
WORKDIR /app
COPY --from=builder /opt/deps /opt/deps
COPY . .
ENV PYTHONPATH=/opt/deps
USER nonroot:nonroot
EXPOSE 8000
CMD ["-m", "gunicorn", "app:app", "--bind", "0.0.0.0:8000"]
pip install --target=/opt/deps deja los paquetes planos en disco — copiables, sin symlinks. Mejor que el truco habitual de COPY --from=builder /opt/venv: el bin/python de un venv es un symlink a la ruta del intérprete del builder (/usr/local/bin/python3.x), que no existe dentro de distroless, así que el venv copiado no arranca. Un matiz: distroless/python3 sigue experimental y fija una versión concreta del intérprete — empareja el python:3.11-slim del builder con ella, o vuelve a python:3.12-slim como runtime manteniendo el mismo patrón --target.
Multi-stage con scratch para Go
# Stage 1: Build
FROM golang:1.22-alpine AS builder
WORKDIR /build
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o server .
# Stage 2: Runtime (scratch = imagen vacía)
FROM scratch AS runtime
COPY --from=builder /build/server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
EXPOSE 8080
ENTRYPOINT ["/server"]
scratch es una imagen de cero bytes — lo único en tu contenedor es tu binario. CGO_ENABLED=0 es obligatorio (no hay libc contra la que enlazar), y el bundle de CA tiene que venir con él porque scratch no trae nada, ni certificados. Si eso suena a armar el SO a mano, lo es — static-debian12 es scratch más los pocos archivos que cualquier app real necesita (certs, tzdata, una entrada passwd de nonroot), por eso la mayoría de equipos aterrizan ahí.
Multi-stage con Gradle para Java
# Stage 1: Build
FROM gradle:8.7-jdk21-alpine AS builder
WORKDIR /build
COPY build.gradle settings.gradle ./
COPY src ./src
RUN gradle bootJar --no-daemon
# Stage 2: Runtime
FROM eclipse-temurin:21-jre-alpine AS runtime
WORKDIR /app
COPY --from=builder /build/build/libs/*.jar app.jar
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
JRE Alpine no trae ningún usuario de cortesía — USER temurin suena plausible y falla en runtime (“unable to find user”). Crea uno, o quita la línea USER del todo. Y usa ENTRYPOINT en forma exec aquí: el jar dentro de CMD funcionaría, pero ENTRYPOINT declara que el contenedor es el proceso JVM, lo que hace que señales como SIGTERM lleguen a Java correctamente para un apagado limpio.
.dockerignore para un contexto más pequeño
# .dockerignore
node_modules
dist
.git
.gitignore
.env
.env.local
*.md
.vscode
.idea
coverage
.nyc_output
docker-compose*.yml
El contexto es lo que se sube al daemon antes de que corra una sola capa — en un repo con node_modules/ y .git son rutinariamente cientos de MB por build. También protege la caché: un cambio suelto en un archivo ignorado ya no invalida el COPY . ..
Optimización del orden de capas
FROM node:20-alpine AS builder
WORKDIR /app
# Copiar archivos de dependencias primero (cacheado a menos que package.json cambie)
COPY package*.json ./
RUN npm ci
# Copiar fuente (invalida caché solo cuando el código cambia)
COPY . .
RUN npm run build
Docker cachea por capa y tira la caché en la primera instrucción que cambió — todo lo que sigue se reconstruye. Las dependencias cambian a lo sumo semanalmente; el código, varias veces al día. Poner el npm ci caro encima del COPY . . barato hace que un commit de código reutilice la capa de dependencias en lugar de instalar todo de nuevo.
Explicación
Cada FROM abre una imagen limpia, y COPY --from=<etapa> es la única forma de pasar archivos de una a otra. Lo que una etapa no exporta desaparece con ella — el SDK, las cachés, los objetos intermedios. Solo la última etapa termina siendo la imagen tageada.
Para interiorizar:
- Stages nombrados (
AS builder,AS runtime) son direcciones —COPY --from=builderydocker build --target testresuelven contra ellos. .dockerignorees contexto, no imagen — acelera las subidas y protege la caché, pero no achica la imagen en sí.npm ciantes quenpm install—ciinstala exactamente el lockfile y falla si está desincronizado;installpuede reescribirlo, y entonces dos builds del mismo commit pueden producir árboles distintos.- Usuario non-root —
USER node/nonroot/appuserantes del ENTRYPOINT; todo runtime lo necesita, la mayoría no lo incluye. - Quita símbolos —
-ldflags="-s -w"en Go elimina tablas DWARF/de símbolos (~30% del binario) que nada lee en producción.
Variantes
Multi-stage build para Rust
# Stage 1: Build
FROM rust:1.78 AS builder
WORKDIR /build
COPY Cargo.toml Cargo.lock ./
COPY src ./src
RUN cargo build --release
# Stage 2: Runtime
FROM debian:bookworm-slim AS runtime
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates libssl3 && \
rm -rf /var/lib/apt/lists/*
COPY --from=builder /build/target/release/myapp /usr/local/bin/myapp
USER nobody
EXPOSE 8080
CMD ["myapp"]
Rust enlaza glibc dinámicamente por defecto, así que bookworm-slim (~80MB) es el suelo pragmático — o compila con RUSTFLAGS="-C target-feature=+crt-static" y aterriza en scratch/distroless como el ejemplo de Go.
Cache mounts de BuildKit
# syntax=docker/dockerfile:1.7
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
# Montar caché de npm como volumen (persiste entre builds)
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN --mount=type=cache,target=/root/.npm npm run build
# Cache mount para pip
FROM python:3.12-slim AS builder
WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
# Cache mount para módulos de Go
FROM golang:1.22-alpine AS builder
WORKDIR /build
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
CGO_ENABLED=0 go build -ldflags="-s -w" -o server .
Los cache mounts persisten las cachés de los gestores de paquetes en el builder entre builds sin hornearlas en ninguna capa — las descargas de dependencias caen casi a cero en rebuilds. Para velocidad de rebuild en CI nada se le acerca, aunque sí requiere el header # syntax=docker/dockerfile:1.7 y BuildKit — ya el builder por defecto en Docker actual.
Etapa de test para CI
# Stage 1: Dependencias
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci
# Stage 2: Test
FROM deps AS test
COPY . .
RUN npm run lint
RUN npm run test:unit
# Stage 3: Build
FROM deps AS builder
COPY . .
RUN npm run build
# Stage 4: Producción
FROM node:20-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
# Correr solo tests
docker build --target test .
# Build imagen de producción (salta la etapa de test si está cacheada)
docker build --target production -t myapp:latest .
Las etapas solo pagan lo que su cadena de FROM usa: test y deps cuestan tiempo de build pero cero bytes en la imagen final, y --target test te da un job de CI sin publicar nada.
Análisis de tamaño de imagen
# Verificar tamaño de imagen
docker images myapp:latest
# REPOSITORY TAG IMAGE ID CREATED SIZE
# myapp latest abc123 2 minutes ago 148MB
# Analizar tamaños de capas
docker history myapp:latest --no-trunc --format "{{.Size}}\t{{.CreatedBy}}"
# Comparar antes/después
docker images --format "{{.Repository}}:{{.Tag}}\t{{.Size}}" | grep myapp
# Usar dive para análisis detallado de capas
dive myapp:latest
# Muestra cada capa, qué se añadió/removió, y desperdicio potencial
docker history es donde salen las capas sorpresa — un RUN apt-get update suelto que cacheó 40MB de índices, o un paquete de depuración instalado “temporalmente” hace tres meses. dive abre una vista interactiva donde comparas lo que añadió cada capa.
Builds multi-arquitectura
# Dockerfile (igual para todas las plataformas)
FROM --platform=$BUILDPLATFORM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM --platform=$TARGETPLATFORM node:20-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
# Build para amd64 y arm64
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t myapp:latest \
--push .
$BUILDPLATFORM corre la etapa de compilación en la arquitectura de tu host (rápido, nativo) mientras $TARGETPLATFORM produce imágenes finales por arquitectura — QEMU solo emula los pasos baratos de empaquetado, no el compilador.
Mejores Prácticas
- Multi-stage para cualquier cosa más allá de un script — compiladores y gestores de paquetes nunca pertenecen a producción.
- La base más pequeña que funcione: scratch > distroless > alpine > slim > full, en ese orden.
- Dependencias antes que fuente —
COPY package*.json ./encima deCOPY . .deja la capa cara intacta entre commits. npm ci, nuncanpm install, en Dockerfiles — árboles reproducibles o un fallo ruidoso.--omit=dev(npm) /--no-dev(pip) para que las devDependencies no se filtren entre etapas..dockerignoredesde el día uno — el bloat de contexto es invisible hasta que los builds se arrastran.USERno root antes del ENTRYPOINT — crea el usuario si el runtime no lo incluye.-ldflags="-s -w"en Go — ~30% gratis quitando info de depuración que nadie lee.- Encadena la limpieza del gestor de paquetes en el mismo
RUN(apt-get install … && rm -rf /var/lib/apt/lists/*) — cada RUN es una capa, y los archivos borrados siguen pesando en las capas anteriores. - Tagea versiones reales —
:latestno fija nada y los rollbacks dejan de funcionar.
Errores Comunes
- Sin
.dockerignore—node_modulesy.gitviajan al daemon en cada build. COPY . .encima de la instalación de dependencias — cualquier commit vuelve a instalar todo.npm installen CI — el drift del lockfile significa que la imagen testeada no es la publicada.- Publicar el SDK —
COPY --fromes cómo los compiladores se quedan en el builder donde pertenecen. - Correr como root — especialmente absurdo en bases mínimas donde el arreglo son dos líneas.
- Borrar archivos en un
RUNposterior — las capas son aditivas;rmno achica lo que una capa anterior ya pesa. USERcon un nombre que no existe (temurin,app) — créalo primero o el contenedor no arranca.- Asumir que
--targetes solo para tests — también es cómo publicas variantes debug y release desde un solo Dockerfile.
Lecturas Recomendadas
- Docker Docs — Multi-stage builds
- Docker Docs — Caché de build — layer caching y cache mounts
- Docker Docs — Buildx — builds multi-plataforma
- wagoodman/dive — explorador de imagen por capas
Ver También
Preguntas frecuentes
¿Cuánto pueden reducir los multi-stage builds el tamaño de imagen?
Típicamente 80-90 por ciento en runtimes de lenguaje: apps de Node.js bajan de ~900MB a ~150MB, un servicio Go de ~1.2GB a ~15MB sobre scratch. Mide la tuya con docker images --format "{{.Size}}" — el beneficio depende de cuánto toolchain se colaba en producción.
¿Puedo saltar etapas durante el build?
Sí — docker build --target builder para en esa etapa e ignora el resto. Así obtienes una imagen de tests o un builder depurable sin producir la imagen de producción.
¿Cómo depuro una imagen distroless o scratch?
No existe shell dentro, así que docker exec -it sh no aplica. Opciones: construir una variante :debug (distroless publica una con busybox), meter herramientas con docker cp en el contenedor corriendo, o adjuntar un contenedor de depuración efímero en Kubernetes. Para más, mira imágenes distroless con multi-stage builds.
¿Debo usar Alpine o slim?
Alpine es más pequeña (~5MB) pero corre musl libc — las extensiones C de Python y los addons nativos de Node a veces rompen en ella. Slim es compatible con glibc a ~80MB. Empieza con Alpine y cambia a slim si alguna dependencia nativa se niega a compilar sobre musl.
¿Funcionan los cache mounts sin BuildKit?
No — --mount=type=cache necesita BuildKit y el header # syntax=docker/dockerfile:1.7. BuildKit es el builder por defecto en Docker Engine y Docker Desktop actuales, así que en la mayoría de setups funciona directamente.
Recursos Relacionados
Imágenes Docker Distroless con Multi-Stage Builds
Construye imágenes de producción mínimas y sin shell combinando multi-stage builds con bases distroless — ejemplos en Go, Node.js, Python y Java.
DocChecklist de Hardening de Imágenes Docker
Checklist listo para producción para endurecer imágenes Docker: reduce la superficie de ataque, aplica el principio de mínimo privilegio y detecta vulnerabilidades antes del despliegue.
RecipeConfiguración de Docker Health Check para Confiabilidad
Configura HEALTHCHECK de Docker con curl, wget o scripts propios para detectar contenedores que dejan de responder, no solo los que fallan.
RecipeSeguridad en imágenes Docker: escanea, endurece y firma
Escanea imágenes de contenedor en busca de CVEs y secretos con Trivy y Grype. Endurece Dockerfiles, genera SBOMs, firma con Cosign y controla los despliegues.
GuideGuía Completa de Docker en Producción
Ejecuta Docker en producción: multi-stage builds, imágenes distroless, health checks, escaneo, límites de recursos, secrets y seguridad del runtime.