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 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.
Lento: o .next/cache começa vazio
Segundo o guia de cache de build em CI 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:
- 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.
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 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: falseeexperimental.serverSourceMaps: false. Se o build ficar sem memória durante "Generating static pages",enablePrerenderSourceMaps: falsetambé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: truepula 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) |
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=12288no M. - Os caches de pacotes ficam no disco:
~/.npm, o store do pnpm, o~/.cachede cada ferramenta e as versões do Node que osetup-nodeinstalou. Onpm cios lê em vez do registro. - O
.next/cachefica 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óximonext buildcomeça dele, sem step de cache e semNo Cache Detected. O resto do.nexte os outros arquivos não rastreados do checkout são limpos depois de cada trabalho. - As restaurações do
actions/cacheleem 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/cachepara 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
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.
- Entre no Skipbox com o GitHub.
- Instale o app do Skipbox no GitHub e escolha os repositórios.
- Troque o
runs-one 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.
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 19 de novembro de 2026