# Build do Next.js lento ou sem memória no GitHub Actions: cache, memória, tamanho do executor

> Um build do Next.js no GitHub Actions é lento quando o .next/cache não é levado para a próxima execução, e fica sem memória nos 8 GB do ubuntu-latest de um repositório privado quando webpack, checagem de tipos e source maps se somam. O que colocar em cache, quais configurações do Next.js cortam memória e o tamanho do executor: 16 GB por $79 por mês ou 32 GB por $149 no Skipbox, onde o .next/cache fica entre os trabalhos, com minutos ilimitados.

Um build do Next.js no GitHub Actions é lento por um motivo e fica sem memória por outro. Ele é lento quando o `.next/cache` não é levado para a próxima execução: o Next.js reutiliza esse cache entre os builds, um trabalho hospedado pelo GitHub começa em uma VM nova e, sem um step de cache, todo build é a frio (o log diz `No Cache Detected`). Ele fica sem memória porque o `ubuntu-latest` de um repositório privado tem 8 GB, e a compilação webpack, a checagem de tipos e os source maps de um app grande podem passar disso. Resolva o primeiro com `actions/cache` no `.next/cache`. Para o segundo, primeiro as configurações de memória do Next.js (`experimental.webpackMemoryOptimizations`, sem source maps de produção); depois, uma máquina com mais memória: 16 GB ou 32 GB.

O Skipbox dá essa memória ao build a preço fixo: 16 GB e 8 vCPU em `runs-on: skipbox-8x16` por $79 por mês, 32 GB e 16 vCPU em `skipbox-16x32` por $149. Na sua máquina dedicada, o `.next/cache` fica para o próximo build, os caches de pacotes ficam no disco e o que o `actions/cache` salva é lido localmente, com minutos ilimitados.

- O `.next/cache` fica na sua máquina dedicada: o próximo build reutiliza a última compilação, sem step de cache
- 16 GB por $79 por mês ou 32 GB por $149, contra 8 GB em um `ubuntu-latest` privado
- Os caches de pacotes ficam na sua máquina, e as restaurações de cache leem o disco dela em vez de baixar

**GitHub Actions a preço fixo, minutos ilimitados** O Skipbox roda os seus trabalhos do GitHub Actions na sua própria máquina dedicada: $39 por mês, não importa quantos minutos você rode. As camadas Docker e o cache de dependências ficam entre os trabalhos, então o próximo trabalho começa na hora.

Um executor de 4 vCPU, 20.000 minutos por mês: GitHub $222 → Skipbox $39. Você economiza $183 todo mês.

A mudança é uma linha: `runs-on: skipbox`.

[Começar meu teste grátis de 7 dias](https://app.skipbox.dev/sign-in?ref=g-nextjs-build-slow-out-of-memory-github-actions-pt-br)

## Lento: o .next/cache começa vazio

Segundo o [guia de cache de build em CI](https://nextjs.org/docs/app/guides/ci-build-caching) do Next.js: o Next.js salva um cache em `.next/cache` que é compartilhado entre os builds, e um CI que não o mantém entre os builds mostra um erro `No Cache Detected`. O step dele para o 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') }}-
```

A chave muda a cada mudança no código, então cada execução salva uma entrada nova, dentro dos 10 GB por repositório do GitHub. Em um Turborepo, exclua o `.next/cache` dos `outputs` da tarefa (`"!.next/cache/**"`), como faz o [guia de GitHub Actions do Turborepo](https://turborepo.dev/docs/guides/ci-vendors/github-actions).

## Sem memória: dois erros diferentes

| No log | O que acabou | O que fazer |
|---|---|---|
| `JavaScript heap out of memory` | O limite de heap do próprio Node; a máquina ainda tinha memória | Aumente-o: `NODE_OPTIONS=--max-old-space-size=6144`, abaixo da memória da máquina |
| `Process completed with exit code 137` | A memória da máquina: o Linux matou o processo | Use menos memória, ou uma máquina com mais |

Aumentar o heap além da memória da máquina transforma o primeiro erro no segundo.

## Use menos memória: as configurações do próprio Next.js

Segundo o [guia de uso de memória](https://nextjs.org/docs/app/guides/memory-usage) do Next.js:

- **`experimental.webpackMemoryOptimizations: true`** (v15.0.0 em diante) reduz o pico de memória do webpack, com uma compilação um pouco mais longa.
- **O build worker do webpack** roda a compilação em um worker do Node separado, o que reduz a memória. Ele vem ligado por padrão desde a v14.1.0, a menos que você tenha uma configuração webpack personalizada; com uma, defina `experimental.webpackBuildWorker: true`.
- **Source maps desligados:** `productionBrowserSourceMaps: false` e `experimental.serverSourceMaps: false`. Se o build ficar sem memória durante "Generating static pages", `enablePrerenderSourceMaps: false` também.
- **Meça:** `next build --experimental-debug-memory-usage` (v14.2.0 em diante) mostra o uso de heap ao longo do build e tira heap snapshots perto do limite.
- **Checagem de tipos:** `typescript.ignoreBuildErrors: true` pula a checagem de tipos e a memória dela, e deixa erros de tipo entrarem no build. O Next.js desaconselha isso, a menos que outro step cheque os tipos.

## Use uma máquina com mais memória

| Executor | CPU e memória | Quem pode usar |
|---|---|---|
| GitHub `ubuntu-latest`, repositório privado | 2 CPUs, 8 GB | Todos |
| GitHub `ubuntu-latest`, repositório público | 4 CPUs, 16 GB | Repositórios públicos |
| Executor maior do GitHub, 4 ou 8 núcleos | 16 GB ou 32 GB | Organizações no GitHub Team e no Enterprise Cloud, por minuto ([executores maiores](https://docs.github.com/en/actions/concepts/runners/larger-runners)) |
| Skipbox `skipbox-8x16` | 8 vCPU, 16 GB | Organizações e contas pessoais, $79 por mês |
| Skipbox `skipbox-16x32` | 16 vCPU, 32 GB | Organizações e contas pessoais, $149 por mês |

Com 20.000 minutos por mês, o executor de 8 núcleos do GitHub custa $422 e o Skipbox M $79; com 16 núcleos, $822 contra $149 do L. Os valores do GitHub são depois do uso incluído no GitHub Team.

## O que o Skipbox faz por um build do Next.js

Cada plano vem com a máquina dedicada da sua conta, mantida entre os trabalhos:

- **A memória de que o build precisa**, pelo rótulo: 16 GB no M, 32 GB no L. Ajuste o heap de acordo, como `--max-old-space-size=12288` no M.
- **Os caches de pacotes ficam no disco:** `~/.npm`, o store do pnpm, o `~/.cache` de cada ferramenta e as versões do Node que o `setup-node` instalou. O `npm ci` os lê em vez do registro.
- **O `.next/cache` fica para o próximo trabalho.** A máquina guarda o seu checkout entre os trabalhos e, dentro dele, o `.next/cache`, em qualquer profundidade de um monorepo (`apps/web/.next/cache`). O próximo `next build` começa dele, sem step de cache e sem `No Cache Detected`. O resto do `.next` e os outros arquivos não rastreados do checkout são limpos depois de cada trabalho.
- **As restaurações do `actions/cache` leem a máquina.** O que ele salva fica ao lado da máquina, com mais espaço que os 10 GB por repositório do GitHub, e a restauração é uma leitura local. Mantenha o step do `.next/cache` para os trabalhos que rodam em uma VM nova; na sua máquina dedicada, a restauração deixa o cache guardado como está.
- **Mais núcleos a preço fixo.** A compilação e a geração das páginas estáticas os usam, e os minutos são ilimitados.

| Rótulo | Máquina | Plano |
|---|---|---|
| `skipbox` | 4 vCPU · 16 GB | S, $39 por mês |
| `skipbox-8x16` | 8 vCPU · 16 GB | M, $79 por mês |
| `skipbox-16x32` | 16 vCPU · 32 GB | L, $149 por mês |

## Mudar é uma linha

```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
```

O `skipbox-8x16` roda em um plano M; o teste roda `runs-on: skipbox`.

1. Entre no Skipbox com o GitHub.
2. Instale o app do Skipbox no GitHub e escolha os repositórios.
3. Troque o `runs-on` e faça push.

## Segurança

- A máquina é só da sua conta. Nenhum trabalho de outra empresa roda nela.
- Depois de cada trabalho, as credenciais, os processos e os contêineres do executor são apagados, e também as credenciais do git no checkout mantido e os arquivos não rastreados dele, exceto caches de build como o `.next/cache`. Limpar a cada trabalho dá, em vez disso, uma máquina nova a cada trabalho.
- O código de pessoas sem acesso de escrita (como pull requests de forks) roda em uma VM nova que lê os seus caches mas não pode alterá-los.

Os detalhes estão em [como os trabalhos são isolados](https://docs.skipbox.dev/pt-br/isolation).

## Teste no build do Next.js

O teste é grátis por 7 dias ou 3.000 minutos de trabalhos, o que vier primeiro, sem cartão. Ele roda `runs-on: skipbox`, com 16 GB, 2× a memória do `ubuntu-latest` de um repositório privado: teste o cache e a memória lá, e mova um build que precisa de mais para o plano L (`skipbox-16x32`, 32 GB).

## Perguntas frequentes

### Por que o next build é lento no GitHub Actions?

Normalmente porque o .next/cache começa vazio. O Next.js salva um cache de build no .next/cache e o reutiliza no build seguinte, mas um trabalho hospedado pelo GitHub é uma VM nova, então sem um step que leve o .next/cache adiante, todo build é a frio e o log avisa No Cache Detected. Acrescente um actions/cache para o .next/cache com chave no lockfile e nos seus arquivos de código. O resto do tempo é a instalação e a compilação em 2 CPUs.

### Que tamanho de executor um build do Next.js deve usar no GitHub Actions?

Memória suficiente para o pico do build. O ubuntu-latest de um repositório privado tem 2 CPUs e 8 GB, e o build webpack, a checagem de tipos e os source maps de um app Next.js grande podem passar disso. Os executores maiores do GitHub têm 16 GB com 4 núcleos e 32 GB com 8, só no GitHub Team ou no Enterprise Cloud, por minuto. O Skipbox dá 16 GB com 8 vCPU em runs-on: skipbox-8x16 por $79 por mês, e 32 GB com 16 vCPU em skipbox-16x32 por $149.

### Como resolver JavaScript heap out of memory em um build do Next.js no GitHub Actions?

Esse erro é o limite de heap do próprio Node, não a memória da máquina. Aumente-o com NODE_OPTIONS=--max-old-space-size=<MiB>, abaixo da memória da máquina. Se o trabalho passar a terminar com exit code 137, a própria máquina ficou sem memória: corte a memória do build (experimental.webpackMemoryOptimizations, sem source maps de produção) ou rode em uma máquina com mais memória.

### Como reduzir o uso de memória do build do Next.js?

Segundo o guia de memória do Next.js: experimente o experimental.webpackMemoryOptimizations (v15 em diante), mantenha o build worker do webpack ligado (o padrão sem uma configuração webpack personalizada desde a v14.1.0), desligue o productionBrowserSourceMaps e o experimental.serverSourceMaps, e meça com next build --experimental-debug-memory-usage. Pular a checagem de tipos com typescript.ignoreBuildErrors economiza memória mas deixa passar erros de tipo, então só faça isso quando outro trabalho de CI checar os tipos.

### O Skipbox guarda o .next/cache entre os trabalhos?

Sim. A sua máquina dedicada guarda o checkout entre os trabalhos e, dentro dele, o .next/cache, onde quer que o Next.js o tenha colocado (apps/web/.next/cache em um monorepo), então o próximo next build começa do cache do anterior sem nenhum step de cache. O resto do .next e os outros arquivos não rastreados do checkout são limpos depois de cada trabalho. O cache do npm ou do pnpm, as versões do Node que o setup-node instalou e as camadas do Docker também ficam no disco. Um step de actions/cache para o .next/cache pode continuar: um trabalho em uma VM nova, como um pull request de um fork, restaura a partir dele, e na sua máquina dedicada a restauração deixa o cache guardado como está.

### Quanto custa testar?

Nada. O teste dura 7 dias ou 3.000 minutos de trabalhos, o que vier primeiro, sem cartão, com 4 vCPU e 16 GB: 2× os 8 GB do ubuntu-latest em um repositório privado, o mesmo que o executor maior de 4 núcleos do GitHub. Teste o cache e a memória lá; para um build que precisa de mais, escolha o plano L e troque o rótulo para skipbox-16x32 (32 GB).

Atualizado em 2026-11-19 · https://skipbox.dev/pt-br/guides/nextjs-build-slow-out-of-memory-github-actions
