Saltar al contenido

¿Docker build lento en CI? Encuentre la causa y solúvala

Última actualización

Una compilación de Docker es lenta en CI por una de cinco razones: el contexto de compilación es enorme, las capas están ordenadas de forma que nada se almacena en caché, la caché no sobrevive entre ejecuciones, la imagen hace demasiado en una sola etapa o la máquina es pequeña. Mida primero. La mayoría de las compilaciones tienen una causa dominante, y corregir la equivocada le hará perder una tarde.

Esta es la guía de diagnóstico. Para los propios backends de caché, consulte Caché de Buildx en GitHub Actions. Para los fundamentos de la caché por capas, consulte Caché de capas de Docker en CI.

Paso 1: vea dónde se va el tiempo

Use la salida de progreso sin formato para que cada paso muestre su duración, y active la medición de tiempos de BuildKit:

docker buildx build --progress=plain -t app:test . 2>&1 | tee build.log

Cada paso imprime #N DONE 12.3s, y los que usan caché imprimen CACHED. Lea el registro de arriba abajo y anote tres cosas:

  1. Cuánto tardó load build context o transferring context, y cuántos MB son.
  2. Qué pasos dicen CACHED, y cuáles deberían decirlo.
  3. Cuál es el paso individual más largo.

En una ejecución de GitHub Actions, el mismo registro está en el paso de compilación. Compare una ejecución de una rama que acaba de subir con una nueva ejecución del mismo commit. Si la nueva ejecución es mucho más rápida, su caché funciona en algunos casos y en otros no; si ambas son lentas, no funciona en absoluto.

Paso 2: tamaño del contexto de compilación

La primera línea de una compilación, transferring context: 1.2GB, es una pista clara. Todo lo que hay en el directorio de contexto se envía a BuildKit antes de que se ejecute la primera instrucción, a menos que .dockerignore lo excluya. En CI, esto suele incluir node_modules, .git, artefactos de pruebas, cobertura y salida de compilación.

Un .dockerignore inicial:

.git
node_modules
**/node_modules
dist
build
coverage
*.log
.env*
.github

Por qué importa más allá del tiempo de transferencia: una instrucción COPY . . invalida su capa cuando cambia cualquier archivo del contexto. Contextos grandes y ruidosos hacen que la capa se reconstruya en cada commit y arrastre consigo todas las capas posteriores. Con un buen .dockerignore, el contexto se mantiene estable entre commits.

Compruebe qué se está enviando:

docker buildx build --progress=plain . 2>&1 | grep -i "transferring context"

Paso 3: orden de las capas y fallos de caché

Docker reutiliza una capa solo si su instrucción y todo lo que está encima no han cambiado. Coloque primero lo que cambia raramente y al final lo que cambia en cada commit. El error clásico:

FROM node:22
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build

Cualquier cambio en el código fuente invalida COPY . ., así que npm ci se vuelve a ejecutar en cada compilación. Solución:

FROM node:22
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

Ahora npm ci solo se vuelve a ejecutar cuando cambia el lockfile. La misma idea aplica a todos los ecosistemas: copie los manifiestos, instale y luego copie el código fuente.

Otras cosas que rompen la caché silenciosamente:

  • ARG o ENV con un valor cambiante (un SHA de commit o una fecha de compilación) colocado al principio. Todo lo que está debajo falla. Muévalo al último paso.
  • RUN apt-get update en su propia capa. Se almacena en caché desactualizado. Combine apt-get update && apt-get install -y ... en un solo RUN, y limpie las listas en la misma capa.
  • COPY --from de una imagen base sin fijar. Una etiqueta latest que cambia modifica la capa base. Fije versiones o digests.

Paso 4: la caché no existe en un runner nuevo

Esta es la causa más importante en CI, y es invisible en un portátil. Un runner nuevo alojado en GitHub empieza sin imágenes y sin estado de BuildKit. Cada compilación es completa, incluso con un Dockerfile perfecto. Debe exportar la caché a algún lugar e importarla en la siguiente ejecución, con cache-from y cache-to en docker/build-push-action. Las opciones (caché de GitHub Actions, un registro o un directorio local) y sus límites se explican en Caché de Buildx en GitHub Actions.

Compruebe también el alcance de la caché: las compilaciones de PR leen la caché de main pero no la de otras PR, y el límite de 10 GB por repositorio elimina las entradas antiguas; consulte límites de caché.

Paso 5: compilaciones multietapa

Las compilaciones multietapa ayudan de dos maneras: la imagen final es pequeña, y BuildKit compila en paralelo las etapas independientes y omite las etapas que el destino no necesita.

FROM node:22 AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM deps AS build
COPY . .
RUN npm run build

FROM node:22-slim AS runtime
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
CMD ["node", "dist/server.js"]

Si las pruebas y los linters están en el mismo Dockerfile, dé a cada uno su propia etapa y compílela con --target test en un trabajo separado, para que la compilación de la imagen de ejecución no tenga que esperarla.

Paso 6: ajustes de BuildKit

BuildKit es el compilador predeterminado en las versiones actuales de Docker, y docker/setup-buildx-action configura explícitamente el builder de buildx. Cosas que revisar:

  • Los montajes de caché (RUN --mount=type=cache,target=/root/.npm npm ci) aceleran las instalaciones repetidas en local, pero el montaje vive en el builder, no en la caché de capas exportada. En un runner nuevo empieza vacío. Consulte la sección en la guía de caché de Buildx.
  • Compilaciones multiplataforma. Compilar linux/amd64,linux/arm64 en un runner amd64 emula arm64 con QEMU, lo que puede ser muchas veces más lento. Use runners arm nativos o compile de forma cruzada en la etapa de compilación con --platform=$BUILDPLATFORM.
  • Subida de capas grandes. Si el tiempo se va en exporting to image y en la subida, sus capas son demasiado grandes. Busque COPY de salidas de compilación que no necesita, o chown -R sobre árboles grandes, que duplica cada archivo en una capa nueva. Use COPY --chown.
  • Descargas lentas de la imagen base. Use una base más pequeña o un espejo del registro cercano al runner.

Paso 7: la máquina

Cuando cada paso está bien almacenado en caché y una compilación en frío sigue tardando mucho, el tiempo restante corresponde a la compilación y la compresión, y ambas escalan con la CPU. El runner alojado por GitHub de 2 núcleos es la opción predeterminada. Una máquina más grande reduce el tiempo de compilación, pero no el tiempo de red, así que conviene dejarla para el final. Para builders remotos de Docker dedicados, Depot es una opción muy valorada, diseñada precisamente para este problema; consulte la comparativa con Depot. compiler.dev ejecuta su workflow existente en máquinas de 8 vCPU con una caché de capas de Docker lista, a $0.008 por minuto: consulte los precios y las alternativas a los runners alojados por GitHub.

Lista de verificación rápida

  1. Contexto de menos de unos 100 MB, con un .dockerignore.
  2. Manifiestos copiados e instalados antes del código fuente.
  3. cache-from y cache-to configurados en la acción de build.
  4. Valores variables (SHA, fecha) en las últimas capas.
  5. Etapas independientes, con las pruebas en su propio target.
  6. Builds nativas, no emuladas, para la arquitectura.

Preguntas frecuentes

¿Por qué mi build de Docker es rápida en local y lenta en CI?

Su portátil conserva una caché de capas y un almacén de imágenes. Un runner de CI nuevo empieza vacío, a menos que exporte e importe la caché.

¿.dockerignore acelera las builds?

Sí, por dos motivos: se transfieren menos datos y se invalida la caché con menos frecuencia por archivos que no afectan a la imagen.

¿BuildKit está activado por defecto?

En las versiones actuales de Docker, sí. En GitHub Actions, docker/setup-buildx-action configura un builder de buildx, necesario para la mayoría de backends de caché.

¿Debo crear una build en cada commit?

Solo si necesita la imagen. Cree la build en las pull requests sin publicarla, y publíquela al fusionar. Omitir las builds de imagen cuando no han cambiado los archivos relevantes suele ser la solución más rápida; use filtros paths o una comprobación solo de lo afectado.

¿La caché de GitHub Actions basta para Docker?

Para imágenes pequeñas o medianas, sí. Con imágenes grandes, el límite compartido de 10 GB se convierte en la restricción, y es mejor una caché en un registro.

Ejecute esta compilación de Docker en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis