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

> Ein Next.js-Build in GitHub Actions ist langsam, wenn .next/cache nicht in den nächsten Lauf mitgenommen wird, und ihm geht auf dem ubuntu-latest eines privaten Repositorys mit 8 GB der Speicher aus, sobald sich webpack, Typprüfung und Source Maps summieren. Was du cachen solltest, welche Next.js-Einstellungen den Speicher senken und die Runner-Größe: 16 GB für $79 im Monat oder 32 GB für $149 bei Skipbox, wo .next/cache zwischen den Jobs bleibt, mit unbegrenzten Minuten.

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.

- `.next/cache` bleibt auf deiner dedizierten Maschine: Der nächste Build nutzt sein letztes Kompilat wieder, ohne Cache-Step
- 16 GB für $79 im Monat oder 32 GB für $149, gegenüber 8 GB auf einem privaten `ubuntu-latest`
- Paket-Caches bleiben auf deiner Maschine, und Cache-Wiederherstellungen lesen ihre Festplatte, statt herunterzuladen

**GitHub Actions zum Festpreis, unbegrenzte Minuten** Skipbox führt deine GitHub-Actions-Jobs auf deiner eigenen dedizierten Maschine aus: $39 im Monat, egal wie viele Minuten du nutzt. Docker-Layer und Caches für Abhängigkeiten bleiben zwischen den Jobs erhalten, sodass der nächste Job sofort startet.

Ein Runner mit 4 vCPU, 20.000 Minuten im Monat: GitHub $222 → Skipbox $39. Du sparst jeden Monat $183.

Der Wechsel braucht eine Zeile: `runs-on: skipbox`.

[7-tägige Testphase kostenlos starten](https://app.skipbox.dev/sign-in?ref=g-nextjs-build-slow-out-of-memory-github-actions-de)

## Langsam: .next/cache startet leer

Aus der [Anleitung zum CI-Build-Caching](https://nextjs.org/docs/app/guides/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:

```yaml
- 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](https://turborepo.dev/docs/guides/ci-vendors/github-actions) tut.

## Kein Speicher mehr: zwei verschiedene Fehler

| Im Log | Was ausging | Was zu tun ist |
|---|---|---|
| `JavaScript heap out of memory` | Das eigene Heap-Limit von Node; die Maschine hatte noch Speicher | Erhöhen: `NODE_OPTIONS=--max-old-space-size=6144`, unterhalb des Speichers der Maschine |
| `Process completed with exit code 137` | Der Speicher der Maschine: Linux hat den Prozess beendet | Weniger Speicher nutzen oder eine Maschine mit mehr |

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](https://nextjs.org/docs/app/guides/memory-usage) 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

| Runner | CPU und Speicher | Wer ihn nutzen kann |
|---|---|---|
| GitHub `ubuntu-latest`, privates Repository | 2 CPUs, 8 GB | Alle |
| GitHub `ubuntu-latest`, öffentliches Repository | 4 CPUs, 16 GB | Öffentliche Repositorys |
| Größerer Runner von GitHub, 4 oder 8 Kerne | 16 GB oder 32 GB | Organisationen auf GitHub Team und Enterprise Cloud, pro Minute ([größere Runner](https://docs.github.com/en/actions/concepts/runners/larger-runners)) |
| Skipbox `skipbox-8x16` | 8 vCPU, 16 GB | Organisationen und persönliche Konten, $79 im Monat |
| Skipbox `skipbox-16x32` | 16 vCPU, 32 GB | Organisationen und persönliche Konten, $149 im Monat |

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.

| Label | Maschine | Tarif |
|---|---|---|
| `skipbox` | 4 vCPU · 16 GB | S, $39 im Monat |
| `skipbox-8x16` | 8 vCPU · 16 GB | M, $79 im Monat |
| `skipbox-16x32` | 16 vCPU · 32 GB | L, $149 im Monat |

## Der Wechsel ist eine Zeile

```yaml
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](https://docs.skipbox.dev/de/isolation).

## 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 2026-11-19 · https://skipbox.dev/de/guides/nextjs-build-slow-out-of-memory-github-actions
