Zum Inhalt springen

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:

  1. Wie lange load build context oder transferring context gedauert hat und wie viele MB übertragen wurden.
  2. Welche Schritte CACHED melden und welche es hätten sein sollen.
  3. 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:

  • ARG oder ENV mit 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 update in einem eigenen Layer. Er wird veraltet gecacht. Kombinieren Sie apt-get update && apt-get install -y ... in einem RUN und entfernen Sie die Paketlisten im selben Layer.
  • COPY --from eines nicht fixierten Basis-Images. Ein wandernder latest-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/arm64 auf 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 image und beim Push verloren geht, sind Ihre Layer zu groß. Achten Sie auf COPY von nicht benötigten Build-Ausgaben oder auf chown -R auf großen Verzeichnisbäumen, das jede Datei in einen neuen Layer dupliziert. Verwenden Sie stattdessen COPY --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

  1. Kontext unter etwa 100 MB, mit einer .dockerignore.
  2. Manifeste vor dem Quellcode kopieren und installieren.
  3. cache-from und cache-to in der Build-Action setzen.
  4. Sich ändernde Werte (SHA, Datum) in die letzten Layer verschieben.
  5. Unabhängige Stages, Tests in einem eigenen Target.
  6. 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.

Führen Sie diesen Docker-Build auf compiler.dev aus Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen