Docker-Build in der CI langsam? Ursache finden und beheben
Zuletzt aktualisiert am
Ein Docker-Build ist in der CI aus einem von fünf Gründen langsam: Der Build-Kontext ist riesig, die Layer sind so angeordnet, dass nichts gecacht wird, der Cache bleibt zwischen Läufen nicht erhalten, das Image erledigt zu viel in einer Stage, oder die Maschine ist klein. Messen Sie zuerst. Die meisten Builds haben eine dominierende Ursache, und die falsche zu beheben kostet einen ganzen Nachmittag.
Dies ist der Diagnoseleitfaden. Zu den Cache-Backends selbst siehe Buildx-Cache in GitHub Actions. Zu den Grundlagen des Layer-Cachings siehe Docker-Layer-Caching in der CI.
Schritt 1: Herausfinden, wo die Zeit verloren geht
Verwenden Sie die einfache Fortschrittsausgabe, damit jeder Schritt seine Dauer anzeigt, und aktivieren Sie das Timing von BuildKit:
docker buildx build --progress=plain -t app:test . 2>&1 | tee build.log
Jeder Schritt gibt #N DONE 12.3s aus, gecachte Schritte geben CACHED aus. Lesen Sie das Protokoll von oben nach unten und achten Sie auf drei Dinge:
- Wie lange
load build contextodertransferring contextgedauert hat und wie viele MB übertragen wurden. - Welche Schritte
CACHEDmelden und welche es hätten sein sollen. - Welcher einzelne Schritt am längsten dauert.
Im GitHub Actions-Lauf steht derselbe Log im Build-Schritt. Vergleichen Sie einen Lauf auf einem gerade gepushten Branch mit einem erneuten Lauf desselben Commits. Ist der erneute Lauf deutlich schneller, funktioniert Ihr Cache nur in manchen Fällen; sind beide langsam, funktioniert er gar nicht.
Schritt 2: Größe des Build-Kontexts
Die erste Zeile eines Builds, transferring context: 1.2GB, ist ein deutlicher Hinweis. Alles im Kontextverzeichnis wird an BuildKit gesendet, bevor die erste Anweisung läuft, sofern .dockerignore es nicht ausschließt. In der CI sind hier oft node_modules, .git, Testartefakte, Coverage- und Build-Ausgaben enthalten.
Eine brauchbare Ausgangsbasis für .dockerignore:
.git
node_modules
**/node_modules
dist
build
coverage
*.log
.env*
.github
Warum das über die Übertragungszeit hinaus wichtig ist: Eine Anweisung COPY . . macht ihren Layer ungültig, sobald sich irgendeine Datei im Kontext ändert. Große, unübersichtliche Kontexte bedeuten, dass der Layer bei jedem Commit neu gebaut wird und alle nachfolgenden Layer mitzieht. Mit einer guten .dockerignore bleibt der Kontext zwischen Commits stabil.
Prüfen Sie, was tatsächlich gesendet wird:
docker buildx build --progress=plain . 2>&1 | grep -i "transferring context"
Schritt 3: Layer-Reihenfolge und Cache-Misses
Docker verwendet einen Layer nur dann wieder, wenn seine Anweisung und alles darüber unverändert ist. Platzieren Sie selten geänderte Dinge zuerst und solche, die sich bei jedem Commit ändern, zuletzt. Der klassische Fehler:
FROM node:22
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build
Jede Quelländerung macht COPY . . ungültig, daher läuft npm ci bei jedem Build erneut. Die Lösung:
FROM node:22
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
Jetzt läuft npm ci nur noch dann erneut, wenn sich das Lockfile ändert. Dasselbe Prinzip gilt für jedes Ökosystem: Manifeste kopieren, installieren, dann den Quellcode kopieren.
Weitere Dinge, die den Cache stillschweigend brechen:
ARGoderENVmit einem sich ändernden Wert (ein Commit-SHA oder ein Build-Datum), früh platziert. Alles darunter verfehlt den Cache. Verschieben Sie es an den letzten Schritt.RUN apt-get updatein einem eigenen Layer. Er wird veraltet gecacht. Kombinieren Sieapt-get update && apt-get install -y ...in einemRUNund entfernen Sie die Paketlisten im selben Layer.COPY --fromeines nicht fixierten Basis-Images. Ein wandernderlatest-Tag ändert den Basis-Layer. Fixieren Sie Versionen oder Digests.
Schritt 4: Der Cache existiert auf einem frischen Runner nicht
Das ist die häufigste Ursache in der CI und auf einem Laptop unsichtbar. Ein frischer GitHub-gehosteter Runner startet ohne Images und ohne BuildKit-Zustand. Jeder Build ist ein vollständiger Build, selbst mit einem perfekten Dockerfile. Sie müssen den Cache irgendwo exportieren und beim nächsten Lauf importieren, mit cache-from und cache-to in docker/build-push-action. Die Optionen (GitHub-Actions-Cache, eine Registry, ein lokales Verzeichnis) und ihre Grenzen werden in Buildx-Cache in GitHub Actions behandelt.
Prüfen Sie außerdem den Cache-Scope: PR-Builds lesen den Cache von main, aber nicht den der anderen PRs, und das Limit von 10 GB pro Repository entfernt alte Einträge; siehe Cache-Limits.
Schritt 5: Multi-Stage-Builds
Multi-Stage-Builds helfen auf zwei Arten: Das finale Image ist klein, und BuildKit baut unabhängige Stages parallel und überspringt Stages, die das Ziel nicht benötigt.
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"]
Wenn Tests und Linter im selben Dockerfile stehen, geben Sie ihnen eine eigene Stage und bauen Sie diese mit --target test in einem separaten Job, damit der Build des Laufzeit-Images nicht auf sie wartet.
Schritt 6: BuildKit-Einstellungen
BuildKit ist der Standard-Builder in aktuellem Docker, und docker/setup-buildx-action konfiguriert den Buildx-Builder explizit. Folgendes sollten Sie prüfen:
- Cache-Mounts (
RUN --mount=type=cache,target=/root/.npm npm ci) beschleunigen wiederholte Installationen lokal, aber der Mount liegt auf dem Builder und nicht im exportierten Layer-Cache. Auf einem frischen Runner startet er leer. Siehe den Abschnitt im Buildx-Cache-Leitfaden. - Multi-Plattform-Builds. Ein Build für
linux/amd64,linux/arm64auf einem amd64-Runner emuliert arm64 mit QEMU, was um ein Vielfaches langsamer sein kann. Verwenden Sie native ARM-Runner oder cross-kompilieren Sie in der Build-Stage mit--platform=$BUILDPLATFORM. - Pushen großer Layer. Wenn die Zeit im Schritt
exporting to imageund beim Push verloren geht, sind Ihre Layer zu groß. Achten Sie aufCOPYvon nicht benötigten Build-Ausgaben oder aufchown -Rauf großen Verzeichnisbäumen, das jede Datei in einen neuen Layer dupliziert. Verwenden Sie stattdessenCOPY --chown. - Langsame Pulls der Basis-Images. Verwenden Sie eine kleinere Basis oder einen Registry-Mirror in der Nähe des Runners.
Schritt 7: Die Maschine
Wenn jeder Schritt sinnvoll gecacht ist und ein Cold Build trotzdem lange dauert, entfällt die verbleibende Zeit auf Kompilierung und Komprimierung, und beide skalieren mit der CPU. Der Standard ist ein von GitHub gehosteter Runner mit 2 Kernen. Eine größere Maschine verkürzt die Kompilierzeit, aber nicht die Netzwerkzeit, deshalb sollte man dies zuletzt angehen. Für dedizierte Remote-Docker-Builder ist Depot eine gut angesehene Option, die genau auf dieses Problem ausgerichtet ist; siehe den Depot-Vergleich. compiler.dev führt Ihren bestehenden Workflow auf 8-vCPU-Maschinen mit bereitstehendem Docker-Layer-Cache aus, für $0.008 pro Minute: siehe Preise und Alternativen zu GitHub-gehosteten Runnern.
Eine kurze Checkliste
- Kontext unter etwa 100 MB, mit einer
.dockerignore. - Manifeste vor dem Quellcode kopieren und installieren.
cache-fromundcache-toin der Build-Action setzen.- Sich ändernde Werte (SHA, Datum) in die letzten Layer verschieben.
- Unabhängige Stages, Tests in einem eigenen Target.
- Builds für die native statt eine emulierte Architektur.
FAQ
Warum ist mein Docker-Build lokal schnell und in der CI langsam?
Ihr Laptop verfügt über einen dauerhaften Layer-Cache und Image-Speicher. Ein frischer CI-Runner startet leer, sofern Sie den Cache nicht exportieren und importieren.
Beschleunigt .dockerignore die Builds?
Ja, auf zwei Wegen: Es werden weniger Daten übertragen, und Dateien, die für das Image keine Rolle spielen, invalidieren den Cache seltener.
Ist BuildKit standardmäßig aktiviert?
In aktuellen Docker-Versionen ja. In GitHub Actions richtet docker/setup-buildx-action einen Buildx-Builder ein, der für die meisten Cache-Backends erforderlich ist.
Sollte ich bei jedem Commit bauen?
Nur, wenn Sie das Image benötigen. Bauen Sie bei Pull Requests ohne Push und pushen Sie erst beim Merge. Das Überspringen von Image-Builds, wenn sich keine Docker-Eingaben geändert haben, ist oft die schnellste Lösung; verwenden Sie dafür paths-Filter oder eine Prüfung nur für betroffene Bereiche.
Reicht der GitHub Actions Cache für Docker aus?
Für kleine bis mittelgroße Images ja. Bei großen Images wird das gemeinsame Limit von 10 GB zum Engpass, und dann ist ein Registry-Cache die bessere Wahl.
Verwandt
- Cypress-Tests zu langsam? So beschleunigen Sie CypressCypress-Tests in CI langsam? Beschleunigen mit cy.session, Intercepts und ohne feste Wartezeiten sowie parallele Cypress-Tests in GitHub Actions.
- Jest langsam? Jest-Tests beschleunigen: Worker und --shardJest-Tests zu langsam? Beschleunigen Sie sie mit schnellerer TypeScript-Transformation, passender Worker-Anzahl und --shard in CI. Mit Konfiguration.
- Playwright-Tests langsam in CI? Mit Workern beschleunigenPlaywright-Tests in CI langsam? Beschleunigen mit mehr Workern, wiederverwendetem storageState, gecachten Browsern und --shard. Auch Python.
- Pytest: langsame Tests finden, markieren und beschleunigenLangsame Pytest-Tests finden (--durations), standardmäßig markieren und überspringen, dann mit pytest-xdist und Aufteilung auf CI-Jobs beschleunigen.