Compilaciones Multi-Etapa

Separa las etapas de construcción y tiempo de ejecución para que los compiladores de TypeScript, los ejecutores de pruebas y las dependencias de desarrollo nunca se envíen a producción.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# syntax=docker/dockerfile:1
 
FROM node:24-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
 
FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN npm run build
 
FROM node:24-bookworm-slim AS prod
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/main.js"]

Cuándo usarlo: Cada imagen de API de Node.js. Multi-etapa es el patrón predeterminado para los servicios TypeScript en Node 24.

Ejemplo de Funcionamiento

# syntax=docker/dockerfile:1
 
FROM node:24-bookworm-slim AS base
WORKDIR /app
 
# ---- dependencias (capa en caché) ----
FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci
 
# ---- compilar TypeScript ----
FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN npm run build && npm prune --omit=dev
 
# ---- tiempo de ejecución de producción ----
FROM node:24-bookworm-slim AS prod
WORKDIR /app
ENV NODE_ENV=production
 
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
 
COPY --from=build /app/dist ./dist
 
RUN chown -R node:node /app
USER node
 
HEALTHCHECK CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
 
CMD ["node", "dist/main.js"]

{
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "start": "node dist/main.js"
  }
}

Lo que esto demuestra:

• La etapa deps almacena en caché npm ci cuando solo cambian los archivos fuente
• La etapa build compila TypeScript con todas las dependencias de desarrollo
• La etapa prod copia solo dist/ y los node_modules de producción
• USER node después de chown para un tiempo de ejecución sin root

Análisis Profundo

Cómo Funciona

• Cada FROM inicia una nueva etapa; solo los artefactos COPY --from= cruzan los límites de las etapas
• Las etapas anteriores se descartan de la imagen final, excepto los archivos copiados
• Caché de capas: coloca los pasos lentos (npm ci) antes de los pasos que cambian rápidamente (COPY src)

Patrones de Nomenclatura de Etapas

Montajes de Caché de BuildKit (Opcional)

RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev

Acelera las reconstrucciones de CI cuando el archivo lockfile no ha cambiado. Requiere BuildKit (DOCKER_BUILDKIT=1).

Variante de Monorepo

FROM node:24-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
COPY packages/api/package.json packages/api/
COPY packages/shared/package.json packages/shared/
RUN npm ci
COPY . .
RUN npm run build -w packages/api
 
FROM node:24-bookworm-slim AS prod
WORKDIR /app
COPY --from=build /app/packages/api/dist ./dist
COPY --from=build /app/node_modules ./node_modules
USER node
CMD ["node", "dist/main.js"]

Copia solo el paquete del espacio de trabajo que implementas. No copies todo el monorepo en la etapa de tiempo de ejecución.

Errores Comunes

• npm ci de una sola etapa y luego eliminar manualmente las dependencias de desarrollo - es fácil pasar por alto archivos. Solución: usa una etapa prod dedicada con npm ci --omit=dev.
• Copiar todo /app de la etapa de construcción - arrastra src/, pruebas y cachés a producción. Solución: COPY --from=build /app/dist ./dist solamente.
• Módulos nativos construidos en la etapa incorrecta - bcrypt compilado en macOS, ejecutado en Linux. Solución: compilar dentro de la etapa de construcción de Linux.
• Olvidar package-lock.json en la etapa de producción - npm ci falla o instala versiones incorrectas. Solución: copia el archivo lockfile a cada etapa que ejecute npm ci.
• Ejecutar como root en la etapa final - los escáneres de seguridad lo marcan. Solución: chown + USER node - consulta Contenedores sin Root.
• Contexto de construcción enorme - CI lento. Solución: .dockerignore - consulta Reducción de Tamaño de Imagen.

Alternativas

Preguntas Frecuentes

docker build --target build -t api:debug .
docker run -it --entrypoint sh api:debug

Relacionado

• Conceptos Básicos de Docker - primer contenedor
• Reducción de Tamaño de Imagen - .dockerignore y dieta de capas
• Compensaciones de Distroless y Alpine - bases de tiempo de ejecución mínimas
• Contenedores sin Root - permisos en la etapa final
• Mejores Prácticas de Docker - lista de verificación de la sección

Versiones de Stack: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.