Un multi-stage build permite usar una imagen con compiladores y herramientas para construir la aplicación, y terminar con otra que incluya solo lo necesario para ejecutarla. Así reduces archivos y dependencias de build en el artefacto final, sin tener que preparar manualmente otro entorno de compilación.
En esta lección verás cómo se crean las etapas de un Dockerfile, cómo copiar artefactos entre ellas y cómo comprobar qué etapa produce la imagen final.
👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.
🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.
Qué es un multi-stage build
Un multi-stage build es un Dockerfile que contiene varias etapas. Cada instrucción FROM inicia una etapa nueva, y puedes asignarle un nombre con AS. Luego, COPY –from permite transferir archivos desde una etapa anterior a la que se convertirá en imagen final.
Cómo se relacionan las etapas
| Elemento | Función |
|---|---|
| FROM … AS build | Inicia y nombra la etapa que instala herramientas y compila. |
| FROM … AS runtime | Empieza una imagen independiente para ejecutar la aplicación. |
| COPY –from=build | Trae a runtime solo archivos seleccionados de la etapa build. |
| Última etapa | Es el resultado predeterminado cuando no se indica otra etapa. |
Las etapas pueden usar imágenes base diferentes. La etapa de compilación puede incluir el SDK y las dependencias de desarrollo; la de ejecución puede partir de una variante más pequeña. Solo lo que copies de forma explícita llegará a la última etapa.
Ejemplo: compilar una aplicación Node.js
Este Dockerfile instala las dependencias para compilar, genera el directorio dist y conserva solo dependencias de producción antes de copiar el resultado al runtime. Asume que el proyecto tiene un archivo de bloqueo y que su comando de build genera dist.
# Etapa de compilación
FROM node:22-bookworm AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
RUN npm prune --omit=dev
# Etapa de ejecución
FROM node:22-bookworm-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build --chown=node:node /app/package*.json ./
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
USER node
CMD ["node", "dist/index.js"]La etapa runtime no hereda automáticamente los archivos de build: cada FROM empieza una etapa limpia. Aquí se copian los manifiestos, los módulos de producción y el resultado compilado. Ajusta el comando de inicio y las rutas a tu aplicación; incluye también los assets que el programa necesite en ejecución.
Construye una etapa concreta
De forma predeterminada, Docker construye la última etapa. Durante el desarrollo puedes pedir una etapa nombrada con la opción target para comprobar el entorno de compilación por separado.
docker build --target build -t mi-app:build .
docker build -t mi-app:runtime .La primera orden genera solo build. La segunda, al no especificar target, genera la etapa final runtime.
Antes de ejecutar
- Confirma que la ruta de salida de la compilación coincide con lo que copia el runtime.
- Identifica bibliotecas, certificados y assets que la aplicación necesita al arrancar.
- Comprueba que las etapas usan arquitecturas y bibliotecas compatibles entre sí.
- Prueba la imagen final, no únicamente la etapa de build.
Errores comunes
- Copiar una ruta que no existe: la etapa de compilación no generó el artefacto en ese directorio. Comprueba la salida del build y corrige COPY –from.
- Copiar demasiado: llevar todo el repositorio o node_modules de desarrollo al runtime anula parte de la reducción. Selecciona los archivos necesarios.
- Usar bases incompatibles: un binario compilado para una biblioteca o arquitectura puede no arrancar en la etapa final. Mantén compatibilidad y ejecuta pruebas sobre runtime.
- Esperar que multi-stage acelere por sí solo cada build: su objetivo principal es separar etapas y controlar la imagen final; la caché depende también del orden de las instrucciones.
Lecciones relacionadas del curso
- Cómo reducir el tamaño de una imagen Docker: aplica multi-stage junto con otras técnicas de optimización.
- Cómo elegir una buena imagen base Docker: selecciona la base de la etapa final.
- Buenas prácticas y errores comunes al construir imágenes: revisa problemas comunes en los Dockerfiles.
Documentación oficial y recursos
Con un multi-stage build puedes compilar con las herramientas adecuadas y entregar una imagen final que contiene solo las dependencias y los archivos de ejecución. Revisa las rutas copiadas y prueba siempre la última etapa para confirmar que la aplicación funciona sin el entorno de build.

