# Compilación de Next.js lenta o sin memoria en GitHub Actions: caché, memoria y tamaño del ejecutor

> Una compilación de Next.js en GitHub Actions es lenta cuando .next/cache no pasa a la siguiente ejecución, y se queda sin memoria en el ubuntu-latest de 8 GB de un repositorio privado cuando webpack, la comprobación de tipos y los source maps se suman. Qué guardar en caché, qué ajustes de Next.js reducen la memoria y el tamaño del ejecutor: 16 GB por $79 al mes o 32 GB por $149 en Skipbox, donde .next/cache se conserva entre trabajos y los minutos son ilimitados.

Una compilación de Next.js en GitHub Actions es lenta por una razón y se queda sin memoria por otra. Es lenta cuando `.next/cache` no pasa a la siguiente ejecución: Next.js reutiliza esa caché entre compilaciones, un trabajo hospedado en GitHub empieza en una VM nueva y, sin un paso de caché, cada compilación es en frío (el log dice `No Cache Detected`). Se queda sin memoria porque el `ubuntu-latest` de un repositorio privado tiene 8 GB, y la compilación con webpack, la comprobación de tipos y los source maps de una app grande pueden pasar de ahí. Arregla lo primero con `actions/cache` sobre `.next/cache`. Para lo segundo, primero van los ajustes de memoria de Next.js (`experimental.webpackMemoryOptimizations`, sin source maps de producción); después, una máquina con más memoria: 16 GB o 32 GB.

Skipbox le da esa memoria a la compilación a precio fijo: 16 GB y 8 vCPU con `runs-on: skipbox-8x16` por $79 al mes, 32 GB y 16 vCPU con `skipbox-16x32` por $149. En tu máquina dedicada, `.next/cache` se queda para la siguiente compilación, las cachés de paquetes se quedan en el disco y lo que guarda `actions/cache` se lee en local, con minutos ilimitados.

- `.next/cache` se queda en tu máquina dedicada: la siguiente compilación reutiliza la anterior, sin paso de caché
- 16 GB por $79 al mes o 32 GB por $149, frente a 8 GB en un `ubuntu-latest` privado
- Las cachés de paquetes se quedan en tu máquina, y las restauraciones de caché leen su disco en lugar de descargar

**GitHub Actions a precio fijo, minutos ilimitados** Skipbox ejecuta tus trabajos de GitHub Actions en tu propia máquina dedicada: $39 al mes, ejecutes los minutos que ejecutes. Las capas de Docker y las cachés de dependencias se conservan entre trabajos, así que el siguiente trabajo empieza enseguida.

Un ejecutor de 4 vCPU, 20.000 minutos al mes: GitHub $222 → Skipbox $39. Ahorras $183 cada mes.

Pasarte lleva una sola línea: `runs-on: skipbox`.

[Empezar mi prueba gratuita de 7 días](https://app.skipbox.dev/sign-in?ref=g-nextjs-build-slow-out-of-memory-github-actions-es)

## Lenta: .next/cache empieza vacío

Según la [guía de caché de compilación en CI](https://nextjs.org/docs/app/guides/ci-build-caching) de Next.js: Next.js guarda una caché en `.next/cache` que se comparte entre compilaciones (“saves a cache to `.next/cache` that is shared between builds”), y una CI que no la conserva entre compilaciones muestra un error `No Cache Detected`. Su paso para 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 clave cambia con cada cambio en el código fuente, así que cada ejecución guarda una entrada nueva, dentro de los 10 GB por repositorio de GitHub. En un Turborepo, excluye `.next/cache` de los `outputs` de la tarea (`"!.next/cache/**"`), como hace la [guía de GitHub Actions de Turborepo](https://turborepo.dev/docs/guides/ci-vendors/github-actions).

## Sin memoria: dos errores distintos

| En el log | Qué se agotó | Qué hacer |
|---|---|---|
| `JavaScript heap out of memory` | El límite de heap del propio Node; a la máquina todavía le quedaba memoria | Súbelo: `NODE_OPTIONS=--max-old-space-size=6144`, por debajo de la memoria de la máquina |
| `Process completed with exit code 137` | La memoria de la máquina: Linux mató el proceso | Usa menos memoria, o una máquina con más |

Subir el heap por encima de la memoria de la máquina convierte el primer error en el segundo.

## Usa menos memoria: los ajustes del propio Next.js

Según la [guía de uso de memoria](https://nextjs.org/docs/app/guides/memory-usage) de Next.js:

- **`experimental.webpackMemoryOptimizations: true`** (v15.0.0 y posteriores) baja el pico de memoria de webpack, a cambio de una compilación algo más larga.
- **El build worker de webpack** ejecuta la compilación en un worker de Node aparte, lo que baja la memoria. Está activado por defecto desde v14.1.0 salvo que tengas una configuración personalizada de webpack; con una, configura `experimental.webpackBuildWorker: true`.
- **Source maps desactivados:** `productionBrowserSourceMaps: false` y `experimental.serverSourceMaps: false`. Si la compilación se queda sin memoria durante "Generating static pages", también `enablePrerenderSourceMaps: false`.
- **Mide:** `next build --experimental-debug-memory-usage` (v14.2.0 y posteriores) imprime el uso del heap durante la compilación, y toma snapshots del heap cerca del límite.
- **Comprobación de tipos:** `typescript.ignoreBuildErrors: true` se salta la comprobación de tipos y su memoria, y deja pasar errores de tipos a la compilación. Next.js lo desaconseja salvo que otro paso compruebe los tipos.

## Usa una máquina con más memoria

| Ejecutor | CPU y memoria | Quién puede usarlo |
|---|---|---|
| `ubuntu-latest` de GitHub, repositorio privado | 2 CPU, 8 GB | Todos |
| `ubuntu-latest` de GitHub, repositorio público | 4 CPU, 16 GB | Repositorios públicos |
| Ejecutor más grande de GitHub, 4 u 8 núcleos | 16 GB o 32 GB | Organizaciones con GitHub Team y Enterprise Cloud, por minuto ([ejecutores más grandes](https://docs.github.com/en/actions/concepts/runners/larger-runners)) |
| Skipbox `skipbox-8x16` | 8 vCPU, 16 GB | Organizaciones y cuentas personales, $79 al mes |
| Skipbox `skipbox-16x32` | 16 vCPU, 32 GB | Organizaciones y cuentas personales, $149 al mes |

Con 20.000 minutos al mes, el ejecutor de 8 núcleos de GitHub cuesta $422 y Skipbox M $79; con 16 núcleos, $822 frente a $149 por L. Las cifras de GitHub son después del uso incluido en GitHub Team.

## Lo que Skipbox hace por una compilación de Next.js

Cada plan trae la máquina dedicada de tu cuenta, que se mantiene entre trabajos:

- **La memoria que necesita la compilación**, según la etiqueta: 16 GB en M, 32 GB en L. Ajusta el heap en consecuencia, como `--max-old-space-size=12288` en M.
- **Las cachés de paquetes se quedan en el disco:** `~/.npm`, el store de pnpm, el `~/.cache` de cada herramienta y las versiones de Node que instaló `setup-node`. `npm ci` las lee en lugar del registro.
- **`.next/cache` se queda para el siguiente trabajo.** La máquina conserva tu checkout entre trabajos y, dentro de él, `.next/cache`, a cualquier profundidad de un monorepo (`apps/web/.next/cache`). El siguiente `next build` arranca desde ahí, sin paso de caché y sin `No Cache Detected`. El resto de `.next` y los demás archivos sin seguimiento del checkout se limpian después de cada trabajo.
- **Las restauraciones de `actions/cache` leen la máquina.** Lo que guarda se queda junto a la máquina, con más espacio que los 10 GB por repositorio de GitHub, y la restauración es una lectura local. Mantén el paso de `.next/cache` para los trabajos que corren en una VM nueva; en tu máquina dedicada, la restauración deja la caché conservada tal como está.
- **Más núcleos a precio fijo.** La compilación y la generación de páginas estáticas los usan, y los minutos son ilimitados.

| Etiqueta | Máquina | Plan |
|---|---|---|
| `skipbox` | 4 vCPU · 16 GB | S, $39 al mes |
| `skipbox-8x16` | 8 vCPU · 16 GB | M, $79 al mes |
| `skipbox-16x32` | 16 vCPU · 32 GB | L, $149 al mes |

## Pasarte es una línea

```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` se ejecuta en un plan M; la prueba ejecuta `runs-on: skipbox`.

1. Inicia sesión en Skipbox con GitHub.
2. Instala la app de GitHub de Skipbox y elige los repositorios.
3. Cambia `runs-on` y haz push.

## Seguridad

- La máquina es solo de tu cuenta. Ningún trabajo de otra empresa se ejecuta en ella.
- Después de cada trabajo se borran las credenciales, los procesos y los contenedores del ejecutor, y también las credenciales de git del checkout conservado y sus archivos sin seguimiento, salvo cachés de compilación como `.next/cache`. “VM nueva en cada trabajo” le da a cada trabajo una máquina nueva en su lugar.
- El código de personas sin acceso de escritura (como los pull requests desde forks) se ejecuta en una VM nueva que lee tus cachés pero no puede cambiarlas.

Los detalles están en [cómo se aíslan los trabajos](https://docs.skipbox.dev/es/isolation).

## Pruébalo con la compilación de Next.js

La prueba es gratuita durante 7 días o 3000 minutos de trabajos, lo que ocurra primero, y no pide tarjeta. Ejecuta `runs-on: skipbox`, con 16 GB, 2× la memoria del `ubuntu-latest` de un repositorio privado: prueba ahí la caché y la memoria, y pasa una compilación que necesite más al plan L (`skipbox-16x32`, 32 GB).

## Preguntas frecuentes

### ¿Por qué next build es lento en GitHub Actions?

Normalmente porque .next/cache empieza vacío. Next.js guarda una caché de compilación en .next/cache y la reutiliza en la siguiente compilación, pero un trabajo hospedado en GitHub es una VM nueva, así que sin un paso que traiga .next/cache, cada compilación es en frío y el log avisa No Cache Detected. Agrega actions/cache para .next/cache con una clave basada en el lockfile y tus archivos fuente. El resto del tiempo es la instalación y la compilación en 2 CPU.

### ¿Qué tamaño de ejecutor debería usar una compilación de Next.js en GitHub Actions?

Memoria suficiente para el pico de la compilación. El ubuntu-latest de un repositorio privado tiene 2 CPU y 8 GB, y la compilación con webpack, la comprobación de tipos y los source maps de una app grande de Next.js pueden pasar de ahí. Los ejecutores más grandes de GitHub tienen 16 GB con 4 núcleos y 32 GB con 8, solo en GitHub Team o Enterprise Cloud, por minuto. Skipbox da 16 GB con 8 vCPU en runs-on: skipbox-8x16 por $79 al mes, y 32 GB con 16 vCPU en skipbox-16x32 por $149.

### ¿Cómo arreglo JavaScript heap out of memory en una compilación de Next.js en GitHub Actions?

Ese error es el límite de heap del propio Node, no la memoria de la máquina. Súbelo con NODE_OPTIONS=--max-old-space-size=<MiB>, por debajo de la memoria de la máquina. Si entonces el trabajo termina con exit code 137, la que se quedó sin memoria fue la máquina: reduce la memoria de la compilación (experimental.webpackMemoryOptimizations, sin source maps de producción) o ejecútala en una máquina con más memoria.

### ¿Cómo reduzco el uso de memoria de la compilación de Next.js?

Según la guía de memoria de Next.js: prueba experimental.webpackMemoryOptimizations (v15 y posteriores), deja activado el build worker de webpack (el valor predeterminado sin una configuración personalizada de webpack desde v14.1.0), desactiva productionBrowserSourceMaps y experimental.serverSourceMaps, y mide con next build --experimental-debug-memory-usage. Saltarse la comprobación de tipos con typescript.ignoreBuildErrors ahorra memoria pero deja pasar errores de tipos, así que hazlo solo cuando otro trabajo de CI compruebe los tipos.

### ¿Skipbox conserva .next/cache entre trabajos?

Sí. Tu máquina dedicada conserva el checkout entre trabajos y, dentro de él, .next/cache, esté donde lo haya puesto Next.js (apps/web/.next/cache en un monorepo), así que el siguiente next build arranca desde la caché del anterior sin ningún paso de caché. El resto de .next y los demás archivos sin seguimiento del checkout se limpian después de cada trabajo. La caché de npm o pnpm, las versiones de Node que instaló setup-node y las capas de Docker también se quedan en el disco. Un paso de actions/cache para .next/cache puede quedarse: un trabajo en una VM nueva, como un pull request desde un fork, restaura desde él, y en tu máquina dedicada la restauración deja la caché conservada tal como está.

### ¿Cuánto cuesta probarlo?

Nada. La prueba dura 7 días o 3000 minutos de trabajos, lo que ocurra primero, no pide tarjeta y usa 4 vCPU y 16 GB: 2× los 8 GB de ubuntu-latest en un repositorio privado, y lo mismo que el ejecutor más grande de 4 núcleos de GitHub. Prueba ahí la caché y la memoria; para una compilación que necesite más, elige el plan L y cambia la etiqueta a skipbox-16x32 (32 GB).

Actualizado el 2026-11-19 · https://skipbox.dev/es/guides/nextjs-build-slow-out-of-memory-github-actions
