# Build Next.js lenta o senza memoria in GitHub Actions: cache, memoria, dimensione del runner

> Una build Next.js in GitHub Actions è lenta quando .next/cache non arriva all'esecuzione successiva, e finisce la memoria sull'ubuntu-latest da 8 GB di un repository privato quando webpack, controllo dei tipi e source map si sommano. Cosa mettere in cache, quali impostazioni di Next.js riducono la memoria, e la dimensione del runner: 16 GB per $79 al mese o 32 GB per $149 su Skipbox, dove .next/cache resta tra un job e l'altro e i minuti sono illimitati.

Una build Next.js in GitHub Actions è lenta per un motivo e finisce la memoria per un altro. È lenta quando `.next/cache` non arriva all'esecuzione successiva: Next.js riusa quella cache tra una build e l'altra, un job ospitato da GitHub parte su una VM nuova, e senza uno step di cache ogni build è a freddo (il log dice `No Cache Detected`). Finisce la memoria perché l'`ubuntu-latest` di un repository privato ha 8 GB, e la compilazione webpack, il controllo dei tipi e le source map di una grande app possono superarli. Risolvi il primo con `actions/cache` su `.next/cache`. Per il secondo, vengono prima le impostazioni di memoria di Next.js (`experimental.webpackMemoryOptimizations`, niente source map in produzione); poi una macchina con più memoria: 16 GB o 32 GB.

Skipbox dà alla build quella memoria a prezzo fisso: 16 GB e 8 vCPU su `runs-on: skipbox-8x16` per $79 al mese, 32 GB e 16 vCPU su `skipbox-16x32` per $149. Sulla tua macchina `.next/cache` resta per la build successiva, le cache dei pacchetti restano sul disco e quello che salva `actions/cache` si legge in locale, con minuti illimitati.

- `.next/cache` resta sulla tua macchina: la build successiva riusa la sua ultima compilazione, senza step di cache
- 16 GB per $79 al mese o 32 GB per $149, contro 8 GB su un `ubuntu-latest` privato
- Le cache dei pacchetti restano sulla tua macchina, e i ripristini della cache leggono il suo disco invece di scaricare

**GitHub Actions a prezzo fisso, minuti illimitati** Skipbox esegue i tuoi job di GitHub Actions su una macchina dedicata tutta tua: $39 al mese, per quanti minuti tu esegua. I layer Docker e le cache delle dipendenze restano tra un job e l'altro, così il job successivo parte subito.

Un runner da 4 vCPU, 20.000 minuti al mese: GitHub $222 → Skipbox $39. Risparmi $183 ogni mese.

Per passare basta una riga: `runs-on: skipbox`.

[Inizia la prova gratuita di 7 giorni](https://app.skipbox.dev/sign-in?ref=g-nextjs-build-slow-out-of-memory-github-actions-it)

## Lenta: .next/cache parte vuota

Dalla [guida al caching delle build in CI](https://nextjs.org/docs/app/guides/ci-build-caching) di Next.js: Next.js "saves a cache to `.next/cache` that is shared between builds", e una CI che non la conserva tra una build e l'altra mostra un errore `No Cache Detected`. Il suo step per 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') }}-
```

La chiave cambia a ogni modifica dei sorgenti, quindi ogni esecuzione salva una nuova voce, dentro i 10 GB per repository di GitHub. In un Turborepo, escludi `.next/cache` dagli `outputs` del task (`"!.next/cache/**"`), come fa la [guida di Turborepo per GitHub Actions](https://turborepo.dev/docs/guides/ci-vendors/github-actions).

## Memoria esaurita: due errori diversi

| Nel log | Cosa è finito | Cosa fare |
|---|---|---|
| `JavaScript heap out of memory` | Il limite di heap di Node; la macchina aveva ancora memoria | Alzalo: `NODE_OPTIONS=--max-old-space-size=6144`, sotto la memoria della macchina |
| `Process completed with exit code 137` | La memoria della macchina: Linux ha terminato il processo | Usa meno memoria, o una macchina con più memoria |

Alzare l'heap oltre la memoria della macchina trasforma il primo errore nel secondo.

## Usa meno memoria: le impostazioni di Next.js

Dalla [guida all'uso della memoria](https://nextjs.org/docs/app/guides/memory-usage) di Next.js:

- **`experimental.webpackMemoryOptimizations: true`** (dalla v15.0.0) abbassa il picco di memoria di webpack, con una compilazione un po' più lunga.
- **Il build worker di webpack** esegue la compilazione in un worker Node separato, il che abbassa la memoria. È attivo di default dalla v14.1.0, a meno che tu non abbia una config webpack personalizzata; in quel caso, imposta `experimental.webpackBuildWorker: true`.
- **Source map spente:** `productionBrowserSourceMaps: false` ed `experimental.serverSourceMaps: false`. Se la build finisce la memoria durante "Generating static pages", anche `enablePrerenderSourceMaps: false`.
- **Misura:** `next build --experimental-debug-memory-usage` (dalla v14.2.0) stampa l'uso dell'heap durante la build, e cattura heap snapshot vicino al limite.
- **Controllo dei tipi:** `typescript.ignoreBuildErrors: true` salta il controllo dei tipi e la sua memoria, e lascia entrare gli errori di tipo nella build. Next.js lo sconsiglia a meno che un altro step non controlli i tipi.

## Usa una macchina con più memoria

| Runner | CPU e memoria | Chi può usarlo |
|---|---|---|
| GitHub `ubuntu-latest`, repository privato | 2 CPU, 8 GB | Tutti |
| GitHub `ubuntu-latest`, repository pubblico | 4 CPU, 16 GB | Repository pubblici |
| Runner più grande di GitHub, 4 o 8 core | 16 GB o 32 GB | Organizzazioni su GitHub Team ed Enterprise Cloud, al minuto ([runner più grandi](https://docs.github.com/en/actions/concepts/runners/larger-runners)) |
| Skipbox `skipbox-8x16` | 8 vCPU, 16 GB | Organizzazioni e account personali, $79 al mese |
| Skipbox `skipbox-16x32` | 16 vCPU, 32 GB | Organizzazioni e account personali, $149 al mese |

A 20.000 minuti al mese, il runner a 8 core di GitHub costa $422 e Skipbox M $79; a 16 core, $822 contro $149 per L. Le cifre di GitHub sono al netto dell'uso incluso in GitHub Team.

## Cosa fa Skipbox per una build Next.js

Ogni piano include la macchina del tuo account, tenuta tra un job e l'altro:

- **La memoria che serve alla build**, per etichetta: 16 GB su M, 32 GB su L. Imposta l'heap di conseguenza, come `--max-old-space-size=12288` su M.
- **Le cache dei pacchetti restano sul disco:** `~/.npm`, lo store di pnpm, la `~/.cache` di ogni tool e le versioni di Node installate da `setup-node`. `npm ci` legge da lì invece che dal registry.
- **`.next/cache` resta per il job successivo.** La macchina tiene il tuo checkout tra un job e l'altro, e con lui `.next/cache`, a qualsiasi profondità la metta un monorepo (`apps/web/.next/cache`). Il `next build` successivo parte da lì, senza step di cache e senza `No Cache Detected`. Il resto di `.next` e gli altri file non tracciati del checkout vengono puliti dopo ogni job.
- **I ripristini di `actions/cache` leggono la macchina.** Quello che salva resta accanto alla macchina, con più spazio dei 10 GB per repository di GitHub, e il ripristino è una lettura locale. Tieni lo step per `.next/cache` per i job che girano su una VM nuova; sulla macchina del tuo account il ripristino lascia com'è la cache conservata.
- **Più core a prezzo fisso.** La compilazione e la generazione delle pagine statiche li usano, e i minuti sono illimitati.

| Etichetta | Macchina | Piano |
|---|---|---|
| `skipbox` | 4 vCPU · 16 GB | S, $39 al mese |
| `skipbox-8x16` | 8 vCPU · 16 GB | M, $79 al mese |
| `skipbox-16x32` | 16 vCPU · 32 GB | L, $149 al mese |

## Basta una riga

```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` gira su un piano M; la prova esegue `runs-on: skipbox`.

1. Accedi a Skipbox con GitHub.
2. Installa la GitHub App di Skipbox e scegli i repository.
3. Cambia `runs-on` e fai push.

## Sicurezza

- La macchina è solo del tuo account. Nessun job di altre aziende gira su di essa.
- Dopo ogni job vengono cancellati le credenziali, i processi e i container del runner, e anche le credenziali git del checkout conservato e i suoi file non tracciati diversi dalle cache di build come `.next/cache`. “VM nuova per ogni job” dà invece a ogni job una macchina nuova.
- Il codice di chi non ha accesso in scrittura (come le pull request dai fork) gira su una VM nuova che legge le tue cache ma non le può modificare.

I dettagli sono in [come vengono isolati i job](https://docs.skipbox.dev/it/isolation).

## Provalo sulla build Next.js

La prova è gratuita per 7 giorni o 3000 minuti di job, quello che arriva prima, senza carta. Esegue `runs-on: skipbox`, con 16 GB, 2× la memoria dell'`ubuntu-latest` di un repository privato: prova lì la cache e la memoria, e sposta una build che ha bisogno di più sul piano L (`skipbox-16x32`, 32 GB).

## Domande frequenti

### Perché next build è lento in GitHub Actions?

Di solito perché .next/cache parte vuota. Next.js salva una cache di build in .next/cache e la riusa alla build successiva, ma un job ospitato da GitHub è una VM nuova, quindi senza uno step che riporti .next/cache ogni build è a freddo e il log avverte No Cache Detected. Aggiungi actions/cache per .next/cache con una chiave basata sul lockfile e sui file sorgente. Il resto del tempo è l'installazione e la compilazione su 2 CPU.

### Che dimensione di runner dovrebbe usare una build Next.js in GitHub Actions?

Abbastanza memoria per il picco della build. L'ubuntu-latest di un repository privato ha 2 CPU e 8 GB, e la build webpack, il controllo dei tipi e le source map di una grande app Next.js possono superarli. I runner più grandi di GitHub hanno 16 GB a 4 core e 32 GB a 8, solo su GitHub Team o Enterprise Cloud, al minuto. Skipbox dà 16 GB con 8 vCPU su runs-on: skipbox-8x16 per $79 al mese, e 32 GB con 16 vCPU su skipbox-16x32 per $149.

### Come risolvo JavaScript heap out of memory in una build Next.js su GitHub Actions?

Quell'errore è il limite di heap di Node, non la memoria della macchina. Alzalo con NODE_OPTIONS=--max-old-space-size=<MiB>, sotto la memoria della macchina. Se poi il job finisce invece con exit code 137, è la macchina stessa ad aver finito la memoria: riduci la memoria della build (experimental.webpackMemoryOptimizations, niente source map in produzione) o esegui su una macchina con più memoria.

### Come riduco l'uso di memoria della build Next.js?

Dalla guida alla memoria di Next.js: prova experimental.webpackMemoryOptimizations (dalla v15), tieni attivo il build worker di webpack (il default senza una config webpack personalizzata dalla v14.1.0), disattiva productionBrowserSourceMaps ed experimental.serverSourceMaps, e misura con next build --experimental-debug-memory-usage. Saltare il controllo dei tipi con typescript.ignoreBuildErrors risparmia memoria ma lascia passare gli errori di tipo, quindi fallo solo quando un altro job di CI controlla i tipi.

### Skipbox conserva .next/cache tra un job e l'altro?

Sì. La macchina del tuo account tiene il checkout tra un job e l'altro, e con lui .next/cache, ovunque Next.js l'abbia messa (apps/web/.next/cache in un monorepo), quindi il next build successivo parte dalla cache dell'ultimo senza nessuno step di cache. Il resto di .next e gli altri file non tracciati del checkout vengono puliti dopo ogni job. Anche la cache di npm o pnpm, le versioni di Node installate da setup-node e i layer di Docker restano sul disco. Uno step actions/cache per .next/cache può restare: un job su una VM nuova, come una pull request da un fork, ripristina da lì, e sulla macchina del tuo account il ripristino lascia com'è la cache conservata.

### Quanto costa provarlo?

Niente. La prova dura 7 giorni o 3000 minuti di job, quello che arriva prima, senza carta, su 4 vCPU e 16 GB: 2× i 8 GB di ubuntu-latest su un repository privato, e quanto il runner più grande di GitHub a 4 core. Prova lì la cache e la memoria; per una build che ha bisogno di più, scegli il piano L e cambia l'etichetta in skipbox-16x32 (32 GB).

Aggiornata il giorno 2026-11-16 · https://skipbox.dev/it/guides/nextjs-build-slow-out-of-memory-github-actions
