Skipbox

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

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

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.

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.

  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.

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

CI/CD mais rápido com um cache sempre aquecido

Seu executor aquecido a preço fixo

Nós hospedamos. Você muda uma linha. 1/12 do custo do GitHub com uso total. Preço fixo, então rode o dia todo. 7× o espaço de cache do GitHub.

  • Sem cartão
  • Entrar com o GitHub
  • Cancele quando quiser