Next.js in GitHub Actions beschleunigen
Zuletzt aktualisiert am
Der schnellste Weg, Next.js in GitHub Actions zu beschleunigen, besteht darin, .next/cache zwischen den Runs zu erhalten und in jedem Job nicht immer wieder dieselben Dinge zu installieren und zu bauen. Ein next build ohne Cache kompiliert und optimiert alles neu. Mit Cache werden Compiler- und Image-Caches wiederverwendet, und nur geänderte Dateien werden neu verarbeitet.
Dieser Leitfaden behandelt die tatsächlichen Kosten einer Next.js-Pipeline: Installation, Build, Typprüfung, Unit-Tests und End-to-End-Tests. Er ist die Next.js-Variante unserer allgemeinen Anleitung zur Beschleunigung von GitHub Actions.
Wo die Zeit verloren geht
Ein typischer Next.js-Workflow führt fünf Schritte aus: Abhängigkeiten installieren, Linting, Typprüfung, Build und Tests. Auf einem Runner mit 2 vCPUs ist der Build oft der längste Schritt, und next build warnt, wenn etwas behebbar langsam ist: "No Cache Detected". Diese Meldung bedeutet, dass .next/cache leer war. Next.js dokumentiert das in seinem Leitfaden zum CI-Build-Caching.
Sehen Sie sich zuerst die Zeiten der einzelnen Schritte an. Wenn die Installation 60 Sekunden und der Build drei Minuten dauert, beheben Sie zuerst den Build-Cache.
.next/cache und den Paket-Manager cachen
Next.js speichert seine Ausgabe von Compiler und Optimierung in .next/cache. Der offizielle Leitfaden zeigt einen Schlüssel aus dem Hash der Lockfile plus einem Hash der Quelldateien, mit einem restore-keys-Fallback. Dieser Fallback ist wichtig: Ändern Sie eine Quelldatei, trifft der exakte Schlüssel nicht, doch der Restore-Key stellt den vorherigen Cache wieder her, sodass nur geänderte Dateien neu gebaut werden.
name: ci
on:
pull_request:
push:
branches: [main]
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
- uses: actions/cache@v6
with:
path: ${{ github.workspace }}/.next/cache
key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
restore-keys: |
${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
- run: npm ci
- run: npm run build
Zwei Details. Erstens cacht actions/setup-node mit cache: npm den npm-Download-Cache, nicht node_modules. npm ci führt also weiterhin eine saubere Installation durch, überspringt aber die Downloads. Für andere Paket-Manager verwenden Sie cache: pnpm oder cache: yarn. Zweitens sind GitHub-Cache-Einträge unveränderlich: Ein Run kann nur einen Schlüssel speichern, der noch nicht existiert. Ein Schlüssel mit Quell-Hash erzeugt bei fast jedem PR einen neuen Eintrag und füllt Ihr Kontingent. Die Regeln zur Entfernung finden Sie unter Cache-Limits von GitHub Actions, und mit dem Cache-Key-Builder können Sie andere Schlüssel ausprobieren.
Die Arbeit in parallele Jobs aufteilen
Linting, Typprüfung und Unit-Tests brauchen die Build-Ausgabe nicht. Führen Sie sie als eigene Jobs aus, damit sie sich mit dem Build überschneiden:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
- run: npm ci
- run: npx eslint . --cache --cache-location .eslintcache
- run: npx tsc --noEmit --incremental
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
- run: npm ci
- run: npx vitest run
Jeder Job wiederholt Checkout und Installation, das lohnt sich also nur, solange die Installation gecacht und kurz ist. Wenn Ihre Unit-Tests der langsame Teil sind, lesen Sie Jest langsam oder Vitest langsam.
Turbopack und Build-Zeit
Neuere Next.js-Versionen verwenden Turbopack, einen Bundler in Rust, für next dev und next build. Prüfen Sie in den Release-Notes Ihrer Version, ob next build ihn standardmäßig nutzt und welche Flags zum Aktivieren oder Deaktivieren gelten, da sich das zwischen Releases geändert hat. Turbopack arbeitet mehrfädig und profitiert daher von mehr Kernen als den 2 eines Standard-Hosted-Runners. Er ersetzt .next/cache nicht. Messen Sie next build mit und ohne Turbopack an Ihrer eigenen App und nehmen Sie nichts an.
Weitere Kostenpunkte bei der Build-Zeit, die sich lohnt zu prüfen:
- Telemetrie. Setzen Sie
NEXT_TELEMETRY_DISABLED=1in der CI, damit der Build keine zusätzlichen Aufrufe macht. - Statische Generierung mit API-Aufrufen. Wenn
generateStaticParamsein langsames Backend abfragt, wartet der Build darauf. Verbinden Sie die CI mit einem schnellen Fixture oder Mock. - Bildoptimierung. Viele einzigartige entfernte Bilder verlangsamen den Build. Der Cache hilft bei Wiederholungs-Runs.
- Source Maps. Produktive Browser-Source-Maps kosten Zeit. Deaktivieren Sie sie in CI-Builds, die nur für Tests dienen.
End-to-End-Tests mit Playwright
Playwright ist in einem Next.js-Repository meist der längste Job. Bauen Sie einmal, laden Sie die .next-Ausgabe mit actions/upload-artifact hoch und führen Sie in jedem Shard next start aus, statt pro Shard neu zu bauen. Verwenden Sie das Flag --shard=1/4 von Playwright mit einer Matrix. Das vollständige Rezept, einschließlich des Browser-Caches, finden Sie unter Playwright-Tests langsam und Test-Sharding in GitHub Actions. Der Shard-Rechner hilft bei der Wahl der Shard-Anzahl.
Was mehr CPU-Kerne bringen
next build, tsc, Turbopack und Playwright-Worker nutzen alle mehrere Kerne. Ein 2-vCPU-Runner lässt davon viel ungenutzt. Unsere Benchmarks umfassen zwei Next.js-Stacks, ausgeführt am 8. Oktober 2026 als vollständige CI-Läufe mit 10 Test-Shards und einer echten Datenbank. Turborepo + Next.js + tRPC + MySQL sank von 3m29s auf einem GitHub-gehosteten Runner auf 1m53s auf compiler.dev (1.9x). Next.js + Supabase mit Playwright sank von 4m03s auf 2m48s (1.4x). Dabei handelt es sich um gesamte Pipelines, nicht nur um den Build-Schritt. Betrachten Sie die Werte daher als Anhaltspunkt und nicht als Versprechen für Ihr Repository.
Zum Ausprobieren genügt nach der Installation der GitHub App eine einzige Zeile, runs-on: [self-hosted, Linux, compiler-ci]. Die Standardmaschine hat 8 vCPU und 16 GB und kostet $0.008 pro Minute. Schlägt etwas fehl, greifen die Jobs auf Ihre ursprünglichen Runner zurück. Details finden Sie auf der Preisseite und im Vergleich. Außerdem gibt es ein Next.js-Template und ein allgemeines Node-Template.
Checkliste
- Fügen Sie
actions/cachefür.next/cachemit einem Schlüssel aus Lockfile plus Quellen und einem Restore-Key hinzu. - Aktivieren Sie das Caching für den Paket-Manager über
setup-node. - Führen Sie Linting, Typprüfung, Unit-Tests und Build als parallele Jobs aus.
- Bauen Sie für Playwright einmal und teilen Sie die Tests in Shards auf.
- Fügen Sie
concurrencyundtimeout-minuteshinzu. - Probieren Sie für den Build-Job mehr Kerne aus und vergleichen Sie die Kosten pro Run.
FAQ
Warum meldet next build "No Cache Detected"?
.next/cache war zum Zeitpunkt des Builds leer. Speichern Sie diesen Ordner mit actions/cache zwischen den Runs, wie oben gezeigt, dann verschwindet die Meldung beim nächsten Run.
Sollte ich node_modules in GitHub Actions cachen?
In der Regel nein. Cachen Sie den Download-Cache des Paket-Managers über actions/setup-node und führen Sie ein sauberes npm ci aus. Ein wiederhergestelltes node_modules kann Probleme mit der Lockfile verbergen.
Macht Turbopack Caching überflüssig?
Nein. Turbopack macht die Kompilierung schneller, aber .next/cache speichert weiterhin Ergebnisse und beschleunigt wiederholte Builds. Messen Sie beides in Ihrer App.
Wie beschleunige ich Next.js-Builds in einem Monorepo?
Bauen Sie nur betroffene Apps und nutzen Sie einen Remote-Cache. Siehe Monorepo-CI mit Nx oder Turborepo.
Verwandt
- TypeScript-Monorepo in GitHub Actions beschleunigenTypprüfung und Linting in TypeScript-Monorepos auf GitHub Actions beschleunigen: inkrementelles tsc, Projektreferenzen, Lint-Caches und parallele Jobs.
- Playwright im Monorepo mit GitHub Actions beschleunigenPlaywright-E2E-Tests in einem Node-Monorepo auf GitHub Actions beschleunigen: App einmal bauen, E2E überspringen, wenn sich die Web-App nicht ändert.
- CI-Geschwindigkeits-Badge in Ihre README einfügenZeigen Sie die Geschwindigkeit Ihrer CI mit einem README-Badge: die mediane Laufzeit Ihrer Repository-Workflows auf GitHub Actions, automatisch aktualisiert.
- .NET in GitHub Actions beschleunigen.NET-Builds in GitHub Actions beschleunigen: NuGet-Caching mit setup-dotnet, --no-restore, --no-build, paralleles dotnet test und SQL-Server-Services.