Skipbox

Next.js-Build in GitHub Actions langsam oder ohne Speicher: Cache, Speicher, Runner-Größe

Ein Next.js-Build in GitHub Actions ist aus einem Grund langsam, und aus einem anderen geht ihm der Speicher aus. Langsam ist er, wenn .next/cache nicht in den nächsten Lauf mitgenommen wird: Next.js nutzt diesen Cache zwischen den Builds wieder, ein von GitHub gehosteter Job startet auf einer neuen VM, und ohne Cache-Step ist jeder Build kalt (das Log sagt No Cache Detected). Der Speicher geht ihm aus, weil das ubuntu-latest eines privaten Repositorys 8 GB hat und das webpack-Kompilieren, die Typprüfung und die Source Maps einer großen App darüber hinausgehen können. Das Erste behebst du mit actions/cache auf .next/cache. Für das Zweite kommen zuerst die Speichereinstellungen von Next.js (experimental.webpackMemoryOptimizations, keine Production-Source-Maps); dann eine Maschine mit mehr Speicher: 16 GB oder 32 GB.

Skipbox gibt dem Build diesen Speicher zum Festpreis: 16 GB und 8 vCPU auf runs-on: skipbox-8x16 für $79 im Monat, 32 GB und 16 vCPU auf skipbox-16x32 für $149. Auf deiner dedizierten Maschine bleibt .next/cache für den nächsten Build, die Paket-Caches bleiben auf der Festplatte, und was actions/cache speichert, wird lokal gelesen, mit unbegrenzten Minuten.

Langsam: .next/cache startet leer

Aus der Anleitung zum CI-Build-Caching von Next.js: Next.js „saves a cache to .next/cache that is shared between builds“, speichert also einen Cache in .next/cache, den die Builds teilen, und eine CI, die ihn zwischen den Builds nicht aufbewahrt, zeigt einen No Cache Detected-Fehler. Ihr Step für GitHub Actions:

- uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      ${{ 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') }}-

Der Key ändert sich mit jeder Änderung am Quellcode, also speichert jeder Lauf einen neuen Eintrag, innerhalb der 10 GB von GitHub pro Repository. In einem Turborepo schließ .next/cache aus den outputs der Task aus ("!.next/cache/**"), wie es die Anleitung von Turborepo für GitHub Actions tut.

Kein Speicher mehr: zwei verschiedene Fehler

Den Heap über den Speicher der Maschine hinaus zu erhöhen macht aus dem ersten Fehler den zweiten.

Weniger Speicher nutzen: die eigenen Einstellungen von Next.js

Aus der Anleitung zur Speichernutzung von Next.js:

  • experimental.webpackMemoryOptimizations: true (ab v15.0.0) senkt den Spitzenspeicher von webpack, bei etwas längerem Kompilieren.
  • Der webpack-Build-Worker führt das Kompilieren in einem separaten Node-Worker aus, was den Speicher senkt. Er ist seit v14.1.0 standardmäßig an, außer du hast eine eigene webpack-Konfiguration; mit einer setzt du experimental.webpackBuildWorker: true.
  • Source Maps aus: productionBrowserSourceMaps: false und experimental.serverSourceMaps: false. Geht dem Build bei „Generating static pages“ der Speicher aus, auch enablePrerenderSourceMaps: false.
  • Messen: next build --experimental-debug-memory-usage (ab v14.2.0) gibt die Heap-Nutzung während des Builds aus und erstellt Heap-Snapshots nahe am Limit.
  • Typprüfung: typescript.ignoreBuildErrors: true überspringt die Typprüfung und ihren Speicher und lässt Typfehler in den Build. Next.js rät davon ab, außer ein anderer Step prüft die Typen.

Eine Maschine mit mehr Speicher nutzen

Bei 20.000 Minuten im Monat kostet der 8-Kern-Runner von GitHub $422 und Skipbox M $79; bei 16 Kernen $822 gegenüber $149 für L. Die GitHub-Werte gelten nach Abzug der in GitHub Team enthaltenen Nutzung.

Was Skipbox für einen Next.js-Build tut

Zu jedem Tarif gehört die dedizierte Maschine deines Kontos, die zwischen den Jobs bestehen bleibt:

  • Der Speicher, den der Build braucht, nach Label: 16 GB auf M, 32 GB auf L. Stell den Heap passend ein, etwa --max-old-space-size=12288 auf M.
  • Paket-Caches bleiben auf der Festplatte: ~/.npm, der pnpm-Store, das ~/.cache jedes Tools und die Node-Versionen, die setup-node installiert hat. npm ci liest sie statt der Registry.
  • .next/cache bleibt für den nächsten Job. Die Maschine behält deinen Checkout zwischen den Jobs und darin .next/cache, so tief es ein Monorepo auch ablegt (apps/web/.next/cache). Der nächste next build startet daraus, ohne Cache-Step und ohne No Cache Detected. Der Rest von .next und die übrigen nicht versionierten Dateien des Checkouts werden nach jedem Job aufgeräumt.
  • Wiederherstellungen mit actions/cache lesen die Maschine. Was der Step speichert, bleibt neben der Maschine, mit mehr Platz als den 10 GB von GitHub pro Repository, und die Wiederherstellung ist ein lokaler Lesevorgang. Behalte den Step für .next/cache für Jobs auf einer frischen VM; auf deiner dedizierten Maschine lässt die Wiederherstellung den behaltenen Cache, wie er ist.
  • Mehr Kerne zum Festpreis. Das Kompilieren und das Erzeugen der statischen Seiten nutzen sie, und die Minuten sind unbegrenzt.

Der Wechsel ist eine Zeile

jobs:
  build:
    runs-on: skipbox-8x16 # was ubuntu-latest
    env:
      NODE_OPTIONS: --max-old-space-size=12288
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - uses: actions/cache@v4
        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: npx next build

skipbox-8x16 läuft mit einem M-Tarif; die Testphase führt runs-on: skipbox aus.

  1. Melde dich bei Skipbox mit GitHub an.
  2. Installiere die GitHub-App von Skipbox und wähle die Repositorys.
  3. Ändere runs-on und pushe.

Sicherheit

  • Die Maschine gehört nur deinem Konto. Keine Jobs eines anderen Unternehmens laufen darauf.
  • Nach jedem Job werden die Zugangsdaten, Prozesse und Container des Runners gelöscht, ebenso die Git-Zugangsdaten im behaltenen Checkout und seine nicht versionierten Dateien außer Build-Caches wie .next/cache. „Frische VM für jeden Job“ gibt stattdessen jedem Job eine frische Maschine.
  • Code von Personen ohne Schreibzugriff (etwa Pull Requests aus Forks) läuft auf einer frischen VM, die deine Caches liest, aber nicht ändern kann.

Die Einzelheiten stehen unter Wie Jobs isoliert werden.

Probier es mit dem Next.js-Build

Die Testphase ist kostenlos für 7 Tage oder 3.000 Job-Minuten, je nachdem, was zuerst erreicht ist, ohne Karte. Sie führt runs-on: skipbox aus, mit 16 GB, 2× so viel Speicher wie ubuntu-latest in einem privaten Repository: Probier dort den Cache und den Speicher aus, und verschieb einen Build, der mehr braucht, auf den Tarif L (skipbox-16x32, 32 GB).

FAQ

Warum ist next build in GitHub Actions langsam?

Meist, weil .next/cache leer startet. Next.js speichert einen Build-Cache in .next/cache und nutzt ihn beim nächsten Build wieder, aber ein von GitHub gehosteter Job ist eine neue VM, also ist ohne einen Step, der .next/cache mitnimmt, jeder Build ein kalter, und das Log warnt mit No Cache Detected. Füge actions/cache für .next/cache hinzu, mit einem Key aus dem Lockfile und deinen Quelldateien. Die übrige Zeit sind die Installation und das Kompilieren auf 2 CPUs.

Welche Runner-Größe sollte ein Next.js-Build in GitHub Actions nutzen?

Genug Speicher für die Spitze des Builds. Das ubuntu-latest eines privaten Repositorys hat 2 CPUs und 8 GB, und der webpack-Build, die Typprüfung und die Source Maps einer großen Next.js-App können darüber hinausgehen. Die größeren Runner von GitHub haben 16 GB bei 4 Kernen und 32 GB bei 8, nur auf GitHub Team oder Enterprise Cloud, pro Minute. Skipbox gibt 16 GB mit 8 vCPU auf runs-on: skipbox-8x16 für $79 im Monat und 32 GB mit 16 vCPU auf skipbox-16x32 für $149.

Wie behebe ich JavaScript heap out of memory in einem Next.js-Build auf GitHub Actions?

Dieser Fehler ist das eigene Heap-Limit von Node, nicht der Speicher der Maschine. Erhöhe es mit NODE_OPTIONS=--max-old-space-size=<MiB>, unterhalb des Speichers der Maschine. Endet der Job danach stattdessen mit Exit-Code 137, ging der Maschine selbst der Speicher aus: Senke den Speicherbedarf des Builds (experimental.webpackMemoryOptimizations, keine Production-Source-Maps) oder lass ihn auf einer Maschine mit mehr Speicher laufen.

Wie senke ich den Speicherbedarf eines Next.js-Builds?

Aus der Speicher-Anleitung von Next.js: experimental.webpackMemoryOptimizations ausprobieren (ab v15), den webpack-Build-Worker eingeschaltet lassen (Standard ohne eigene webpack-Konfiguration seit v14.1.0), productionBrowserSourceMaps und experimental.serverSourceMaps ausschalten und mit next build --experimental-debug-memory-usage messen. Die Typprüfung mit typescript.ignoreBuildErrors zu überspringen spart Speicher, lässt aber Typfehler durch, also mach das nur, wenn ein anderer CI-Job die Typen prüft.

Behält Skipbox .next/cache zwischen den Jobs?

Ja. Deine dedizierte Maschine behält den Checkout zwischen den Jobs und darin auch .next/cache, wo immer Next.js es angelegt hat (in einem Monorepo apps/web/.next/cache). Der nächste next build startet also ohne Cache-Step aus dem Cache des letzten. Der Rest von .next und die übrigen nicht versionierten Dateien des Checkouts werden nach jedem Job aufgeräumt. Der Cache von npm oder pnpm, die Node-Versionen, die setup-node installiert hat, und die Layer von Docker bleiben ebenfalls auf der Festplatte. Ein actions/cache-Step für .next/cache kann bleiben: Ein Job auf einer frischen VM, etwa ein Pull Request aus einem Fork, stellt daraus wieder her, und auf deiner dedizierten Maschine lässt die Wiederherstellung den behaltenen Cache, wie er ist.

Was kostet es, das auszuprobieren?

Nichts. Die Testphase dauert 7 Tage oder 3.000 Job-Minuten, je nachdem, was zuerst erreicht ist, ohne Karte, auf 4 vCPU und 16 GB: 2× die 8 GB von ubuntu-latest in einem privaten Repository und genauso viel wie der größere Runner von GitHub mit 4 Kernen. Probier dort das Caching und den Speicher aus; für einen Build, der mehr braucht, wähl den Tarif L und ändere das Label auf skipbox-16x32 (32 GB).

Aktualisiert am 19. November 2026

Schnellere CI/CD mit immer warmem Cache

Dein warmer Runner zum Festpreis

Wir hosten sie. Du änderst eine Zeile. 1/12 der Kosten von GitHub bei voller Auslastung. Zum Festpreis den ganzen Tag laufen lassen. 7× so viel Cache-Speicher wie bei GitHub.

  • Keine Karte
  • Mit GitHub anmelden
  • Jederzeit kündbar