Zum Inhalt springen

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=1 in der CI, damit der Build keine zusätzlichen Aufrufe macht.
  • Statische Generierung mit API-Aufrufen. Wenn generateStaticParams ein 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

  1. Fügen Sie actions/cache für .next/cache mit einem Schlüssel aus Lockfile plus Quellen und einem Restore-Key hinzu.
  2. Aktivieren Sie das Caching für den Paket-Manager über setup-node.
  3. Führen Sie Linting, Typprüfung, Unit-Tests und Build als parallele Jobs aus.
  4. Bauen Sie für Playwright einmal und teilen Sie die Tests in Shards auf.
  5. Fügen Sie concurrency und timeout-minutes hinzu.
  6. 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.

Diesen Workflow auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen