¿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:
- Cuánto tardó
load build contextotransferring context, y cuántos MB son. - Qué pasos dicen
CACHED, y cuáles deberían decirlo. - 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:
ARGoENVcon 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 updateen su propia capa. Se almacena en caché desactualizado. Combineapt-get update && apt-get install -y ...en un soloRUN, y limpie las listas en la misma capa.COPY --fromde una imagen base sin fijar. Una etiquetalatestque 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/arm64en 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 imagey en la subida, sus capas son demasiado grandes. BusqueCOPYde salidas de compilación que no necesita, ochown -Rsobre árboles grandes, que duplica cada archivo en una capa nueva. UseCOPY --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
- Contexto de menos de unos 100 MB, con un
.dockerignore. - Manifiestos copiados e instalados antes del código fuente.
cache-fromycache-toconfigurados en la acción de build.- Valores variables (SHA, fecha) en las últimas capas.
- Etapas independientes, con las pruebas en su propio target.
- 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.
Relacionado
- ¿Sus pruebas de Cypress son lentas? Cómo acelerar Cypress¿Pruebas de Cypress lentas en CI? Cómo acelerar Cypress con cy.session, intercepts y sin esperas fijas, además de pruebas paralelas en GitHub Actions.
- ¿Jest lento? Acelere los tests de Jest: workers y --shard¿Pruebas Jest lentas? Acelérelas con un transform de TypeScript más rápido, el número de workers adecuado y --shard en CI. Encuentre antes las más lentas.
- ¿Playwright lento en CI? Solucione con workers y sharding¿Pruebas de Playwright lentas en CI? Acelérelas con más workers, storageState reutilizado, navegadores en caché y sharding con --shard. Incluye Python.
- Pytest lentos: encontrar, marcar, omitir y acelerar (xdist)Pytest lento: encuentre tests lentos con --durations, márquelos y omítalos por defecto, y acelere con pytest-xdist y repartiendo la suite entre jobs de CI.