Build Next.js lent ou à court de mémoire dans GitHub Actions : cache, mémoire, taille de l'exécuteur
Un build Next.js dans GitHub Actions est lent pour une raison et manque de mémoire pour une autre. Il est lent quand .next/cache n'est pas transmis à l'exécution suivante : Next.js réutilise ce cache entre les builds, une tâche hébergée par GitHub démarre sur une nouvelle VM, et sans étape de cache chaque build part à froid (le log affiche No Cache Detected). Il manque de mémoire parce que l'ubuntu-latest d'un dépôt privé a 8 Go, et la compilation webpack, la vérification des types et les source maps d'une grosse application peuvent dépasser cela. Corrigez le premier avec actions/cache sur .next/cache. Pour le second, les réglages mémoire de Next.js viennent d'abord (experimental.webpackMemoryOptimizations, pas de source maps en production) ; ensuite, une machine avec plus de mémoire : 16 Go ou 32 Go.
Skipbox donne au build cette mémoire à prix fixe : 16 Go et 8 vCPU sur runs-on: skipbox-8x16 pour $79 par mois, 32 Go et 16 vCPU sur skipbox-16x32 pour $149. Sur votre machine dédiée, .next/cache reste pour le build suivant, les caches de paquets restent sur le disque et ce qu'actions/cache enregistre est lu localement, avec des minutes illimitées.
Lent : .next/cache démarre vide
D'après le guide de mise en cache des builds en CI de Next.js : Next.js enregistre dans .next/cache un cache partagé entre les builds, et une CI qui ne le conserve pas d'un build à l'autre affiche une erreur No Cache Detected. Son étape 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') }}-
La clé change à chaque modification du code source : chaque exécution enregistre donc une nouvelle entrée, dans les 10 Go par dépôt de GitHub. Dans un Turborepo, excluez .next/cache des outputs de la tâche ("!.next/cache/**"), comme le fait le guide GitHub Actions de Turborepo.
Manque de mémoire : deux erreurs différentes
| Dans le log | Ce qui a manqué | Que faire |
|---|---|---|
JavaScript heap out of memory | La limite de heap propre à Node ; la machine avait encore de la mémoire | La relever : NODE_OPTIONS=--max-old-space-size=6144, en dessous de la mémoire de la machine |
Process completed with exit code 137 | La mémoire de la machine : Linux a tué le processus | Utiliser moins de mémoire, ou une machine qui en a plus |
Relever le heap au-delà de la mémoire de la machine transforme la première erreur en la seconde.
Utiliser moins de mémoire : les réglages de Next.js
D'après le guide d'utilisation de la mémoire de Next.js :
experimental.webpackMemoryOptimizations: true(v15.0.0 et ultérieures) réduit le pic de mémoire de webpack, au prix d'une compilation un peu plus longue.- Le worker de build webpack exécute la compilation dans un worker Node séparé, ce qui réduit la mémoire. Il est activé par défaut depuis la v14.1.0, sauf si vous avez une configuration webpack personnalisée ; avec une telle configuration, réglez
experimental.webpackBuildWorker: true. - Source maps désactivées :
productionBrowserSourceMaps: falseetexperimental.serverSourceMaps: false. Si le build manque de mémoire pendant « Generating static pages », ajoutez aussienablePrerenderSourceMaps: false. - Mesurer :
next build --experimental-debug-memory-usage(v14.2.0 et ultérieures) affiche l'utilisation du heap tout au long du build, et prend des instantanés du heap à l'approche de la limite. - La vérification des types :
typescript.ignoreBuildErrors: truesaute la vérification des types et sa mémoire, et laisse passer les erreurs de type dans le build. Next.js le déconseille, sauf si une autre étape vérifie les types.
Utiliser une machine avec plus de mémoire
| Exécuteur | CPU et mémoire | Qui peut l'utiliser |
|---|---|---|
GitHub ubuntu-latest, dépôt privé | 2 CPU, 8 Go | Tout le monde |
GitHub ubuntu-latest, dépôt public | 4 CPU, 16 Go | Dépôts publics |
| Exécuteur plus grand de GitHub, 4 ou 8 cœurs | 16 Go ou 32 Go | Organisations GitHub Team et Enterprise Cloud, à la minute (exécuteurs plus grands) |
Skipbox skipbox-8x16 | 8 vCPU, 16 Go | Organisations et comptes personnels, $79 par mois |
Skipbox skipbox-16x32 | 16 vCPU, 32 Go | Organisations et comptes personnels, $149 par mois |
À 20 000 minutes par mois, l'exécuteur 8 cœurs de GitHub coûte $422 et Skipbox M $79 ; en 16 cœurs, $822 contre $149 pour L. Les montants GitHub s'entendent après l'utilisation incluse de GitHub Team.
Ce que Skipbox apporte à un build Next.js
Chaque forfait est livré avec la machine dédiée à votre compte, conservée entre les tâches :
- La mémoire dont le build a besoin, selon le label : 16 Go sur M, 32 Go sur L. Réglez le heap en conséquence, par exemple
--max-old-space-size=12288sur M. - Les caches de paquets restent sur le disque :
~/.npm, le store pnpm, le~/.cachede chaque outil, et les versions de Node installées parsetup-node.npm ciles lit au lieu du registre. .next/cachereste pour la tâche suivante. La machine garde votre checkout d'une tâche à l'autre, et.next/cachededans, à n'importe quelle profondeur d'un monorepo (apps/web/.next/cache). Lenext buildsuivant repart de là, sans étape de cache et sansNo Cache Detected. Le reste de.nextet les autres fichiers non suivis du checkout sont nettoyés après chaque tâche.- Les restaurations d'
actions/cachelisent la machine. Ce que l'étape enregistre reste à côté de la machine, avec plus de place que les 10 Go par dépôt de GitHub, et la restauration est une lecture locale. Gardez l'étape.next/cachepour les tâches qui tournent sur une nouvelle VM ; sur votre machine dédiée, la restauration laisse le cache conservé tel quel. - Plus de cœurs à prix fixe. La compilation et la génération des pages statiques s'en servent, et les minutes sont illimitées.
| Label | Machine | Forfait |
|---|---|---|
skipbox | 4 vCPU · 16 Go | S, $39 par mois |
skipbox-8x16 | 8 vCPU · 16 Go | M, $79 par mois |
skipbox-16x32 | 16 vCPU · 32 Go | L, $149 par mois |
Le passage tient en une ligne
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 s'exécute sur un forfait M ; l'essai exécute runs-on: skipbox.
- Connectez-vous à Skipbox avec GitHub.
- Installez l'application GitHub Skipbox et choisissez les dépôts.
- Modifiez
runs-onet faites un push.
Sécurité
- La machine appartient à votre seul compte. Aucune tâche d'une autre entreprise n'y tourne.
- Après chaque tâche, les identifiants de l'exécuteur, ses processus et ses conteneurs sont effacés, ainsi que les identifiants git du checkout conservé et ses fichiers non suivis, hors caches de build comme
.next/cache. « Nouvelle VM pour chaque tâche » donne plutôt une nouvelle machine à chaque tâche. - Le code des personnes sans accès en écriture (comme les pull requests venant de forks) s'exécute sur une nouvelle VM qui lit vos caches sans pouvoir les modifier.
Les détails sont dans Comment les tâches sont isolées.
Essayez-le sur le build Next.js
L'essai est gratuit pendant 7 jours ou 3 000 minutes de tâches, selon ce qui arrive en premier, sans carte. Il exécute runs-on: skipbox, avec 16 Go, soit 2× la mémoire de l'ubuntu-latest d'un dépôt privé : essayez-y le cache et la mémoire, et passez un build qui a besoin de plus au forfait L (skipbox-16x32, 32 Go).
FAQ
Pourquoi next build est-il lent dans GitHub Actions ?
En général parce que .next/cache démarre vide. Next.js enregistre un cache de build dans .next/cache et le réutilise au build suivant, mais une tâche hébergée par GitHub est une nouvelle VM : sans étape qui transmet .next/cache, chaque build part à froid et le log avertit No Cache Detected. Ajoutez actions/cache pour .next/cache avec une clé basée sur le lockfile et vos fichiers source. Le reste du temps, c'est l'installation et la compilation sur 2 CPU.
Quelle taille d'exécuteur un build Next.js doit-il utiliser dans GitHub Actions ?
Assez de mémoire pour le pic du build. L'ubuntu-latest d'un dépôt privé a 2 CPU et 8 Go, et le build webpack, la vérification des types et les source maps d'une grosse application Next.js peuvent dépasser cela. Les exécuteurs plus grands de GitHub ont 16 Go en 4 cœurs et 32 Go en 8, uniquement sur GitHub Team ou Enterprise Cloud, à la minute. Skipbox donne 16 Go avec 8 vCPU sur runs-on: skipbox-8x16 pour $79 par mois, et 32 Go avec 16 vCPU sur skipbox-16x32 pour $149.
Comment corriger JavaScript heap out of memory dans un build Next.js sur GitHub Actions ?
Cette erreur vient de la limite de heap propre à Node, pas de la mémoire de la machine. Relevez-la avec NODE_OPTIONS=--max-old-space-size=<MiB>, réglée en dessous de la mémoire de la machine. Si la tâche se termine alors par exit code 137, c'est la machine elle-même qui a manqué de mémoire : réduisez la mémoire du build (experimental.webpackMemoryOptimizations, pas de source maps en production) ou exécutez-le sur une machine avec plus de mémoire.
Comment réduire la consommation mémoire d'un build Next.js ?
D'après le guide mémoire de Next.js : essayez experimental.webpackMemoryOptimizations (v15 et ultérieures), gardez le worker de build webpack activé (le défaut sans configuration webpack personnalisée depuis la v14.1.0), désactivez productionBrowserSourceMaps et experimental.serverSourceMaps, et mesurez avec next build --experimental-debug-memory-usage. Sauter la vérification des types avec typescript.ignoreBuildErrors économise de la mémoire mais laisse passer les erreurs de type : ne le faites que si une autre tâche de CI vérifie les types.
Skipbox garde-t-il .next/cache entre les tâches ?
Oui. Votre machine dédiée garde le checkout d'une tâche à l'autre, et .next/cache avec, où que Next.js l'ait placé (apps/web/.next/cache dans un monorepo) : le next build suivant repart du cache du précédent, sans étape de cache. Le reste de .next et les autres fichiers non suivis du checkout sont nettoyés après chaque tâche. Le cache de npm ou de pnpm, les versions de Node installées par setup-node et les couches Docker restent aussi sur le disque. Une étape actions/cache pour .next/cache peut rester : une tâche sur une nouvelle VM, comme une pull request venue d'un fork, restaure à partir d'elle, et sur votre machine dédiée la restauration laisse le cache conservé tel quel.
Combien coûte l'essai ?
Rien. L'essai dure 7 jours ou 3 000 minutes de tâches, selon ce qui arrive en premier, sans carte, sur 4 vCPU et 16 Go : 2× les 8 Go d'ubuntu-latest sur un dépôt privé, et autant que l'exécuteur plus grand à 4 cœurs de GitHub. Essayez-y la mise en cache et la mémoire ; pour un build qui a besoin de plus, choisissez le forfait L et remplacez le label par skipbox-16x32 (32 Go).
Mis à jour le 19 novembre 2026